@voxgig/apidef 2.3.1 → 2.4.0

package/src/guide/heuristic01.ts

@@ -2,12 +2,14 @@
 
 import { each, snakify, names } from 'jostraca'
 
-import { size, walk } from '@voxgig/struct'
+import { size } from '@voxgig/struct'
 
 
 import {
   depluralize,
-  getdlog
+  getdlog,
+  capture,
+  find,
 } from '../utility'
 
 
@@ -29,9 +31,13 @@ type EntityPathDesc = {
 // Log non-fatal wierdness.
 const dlog = getdlog('apidef', __filename)
 
+
 async function heuristic01(ctx: any): Promise<Record<string, any>> {
   let guide = ctx.model.main.api.guide
 
+  const metrics = measure(ctx)
+  // console.dir(metrics, { depth: null })
+
   const entityDescs = resolveEntityDescs(ctx)
 
   guide = {
@@ -43,6 +49,30 @@ async function heuristic01(ctx: any): Promise<Record<string, any>> {
 }
 
 
+function measure(ctx: any) {
+  const metrics = {
+    count: {
+      schema: ({} as Record<string, number>)
+    }
+  }
+
+  let xrefs = find(ctx.def, 'x-ref')
+  // console.log('XREFS', xrefs)
+
+  let schemas = xrefs.filter(xref => xref.val.includes('schema'))
+
+  schemas.map(schema => {
+    let m = schema.val.match(/\/components\/schemas\/(.+)$/)
+    if (m) {
+      const name = m[1]
+      metrics.count.schema[name] = 1 + (metrics.count.schema[name] || 0)
+    }
+  })
+
+
+  return metrics
+}
+
 
 
 
@@ -59,100 +89,111 @@ function resolveEntityDescs(ctx: any) {
   const entityDescs: Record<string, any> = {}
   const paths = ctx.def.paths
 
-  // Analyze paths ending in .../foo/{foo}
-  each(paths, (pathDef: any, pathStr: string) => {
 
-    // Look for rightmmost /entname/{entid}.
-    let m = pathStr.match(/\/([a-zA-Z0-1_-]+)(\/\{([a-zA-Z0-1_-]+)\})?$/)
-    // const m = pathStr.match(/\/([a-zA-Z0-1_-]+)\/\{([a-zA-Z0-1_-]+)\}$/)
-    if (m) {
-      // const entdesc = resolveEntity(entityDescs, pathStr, m[1], m[2])
+  const caught = capture(ctx.def, {
+    paths:
+      ['`$SELECT`', /\/([a-zA-Z0-1_-]+)(\/\{([a-zA-Z0-1_-]+)\})?$/,
+        ['`$SELECT`', /get|post|put|patch|delete/i,
+          ['`$APPEND`', 'methods', {
+            path: '`select$=key.paths`',
+            method: { '`$LOWER`': '`$KEY`' },
+            summary: '`.summary`',
+            parameters: '`.parameters`',
+            responses: '`.responses`',
+            requestBody: '`.requestBody`'
+          }]
+        ]
+      ]
+  })
 
-      each(pathDef, (methodDef: any, methodStr: string) => {
-        // console.log('PPP', pathStr, methodStr, methodDef)
 
-        methodStr = methodStr.toLowerCase()
-        let why_op: string[] = []
+  each(caught.methods, (pmdef) => {
+    let methodDef = pmdef
+    let pathStr = pmdef.path
+    let methodStr = pmdef.method
 
-        if (!METHOD_IDOP[methodStr]) {
-          return
-        }
+    // methodStr = methodStr.toLowerCase()
+    let why_op: string[] = []
 
-        const why_ent: string[] = []
-        const entdesc =
-          resolveEntity(entityDescs, pathDef, pathStr, methodDef, methodStr, why_ent)
+    if (!METHOD_IDOP[methodStr]) {
+      return
+    }
 
+    const why_ent: string[] = []
+    const entdesc =
+      resolveEntity(entityDescs, pathStr, methodDef, methodStr, why_ent)
 
-        if (null == entdesc) {
-          console.log(
-            'WARNING: unable to resolve entity for method ' + methodStr +
-            ' path ' + pathStr)
-          return
-        }
 
-        entdesc.path[pathStr].why_ent = why_ent
+    if (null == entdesc) {
+      console.log(
+        'WARNING: unable to resolve entity for method ' + methodStr +
+        ' path ' + pathStr)
+      return
+    }
 
+    entdesc.path[pathStr].why_ent = why_ent
 
-        // if (pathStr.includes('courses')) {
-        //   console.log('ENTRES', pathStr, methodStr)
-        //   console.dir(ent2, { depth: null })
-        // }
 
-        let opname = resolveOpName(methodStr, methodDef, pathStr, entdesc, why_op)
+    // if (pathStr.includes('courses')) {
+    //   console.log('ENTRES', pathStr, methodStr)
+    //   console.dir(ent2, { depth: null })
+    // }
 
-        if (null == opname) {
-          console.log(
-            'WARNING: unable to resolve operation for method ' + methodStr +
-            ' path ' + pathStr)
-          return
-        }
+    let opname = resolveOpName(methodStr, methodDef, pathStr, entdesc, why_op)
 
+    if (null == opname) {
+      console.log(
+        'WARNING: unable to resolve operation for method ' + methodStr +
+        ' path ' + pathStr)
+      return
+    }
 
-        const transform: Record<string, any> = {
-          // reqform: '`reqdata`',
-          // resform: '`body`',
-        }
 
-        const resokdef = methodDef.responses?.[200] || methodDef.responses?.[201]
-        const resbody = resokdef?.content?.['application/json']?.schema
-        if (resbody) {
-          if (resbody[entdesc.origname]) {
-            transform.resform = '`body.' + entdesc.origname + '`'
-          }
-          else if (resbody[entdesc.name]) {
-            transform.resform = '`body.' + entdesc.name + '`'
-          }
-        }
+    const transform: Record<string, any> = {
+      // reqform: '`reqdata`',
+      // resform: '`body`',
+    }
 
-        const reqdef = methodDef.requestBody?.content?.['application/json']?.schema?.properties
-        if (reqdef) {
-          if (reqdef[entdesc.origname]) {
-            transform.reqform = { [entdesc.origname]: '`reqdata`' }
-          }
-          else if (reqdef[entdesc.origname]) {
-            transform.reqform = { [entdesc.origname]: '`reqdata`' }
-          }
+    const resokdef = methodDef.responses?.[200] || methodDef.responses?.[201]
+    const resbody = resokdef?.content?.['application/json']?.schema
+    if (resbody) {
+      if (resbody[entdesc.origname]) {
+        transform.resform = '`body.' + entdesc.origname + '`'
+      }
+      else if (resbody[entdesc.name]) {
+        transform.resform = '`body.' + entdesc.name + '`'
+      }
+    }
 
-        }
+    const reqdef = methodDef.requestBody?.content?.['application/json']?.schema?.properties
+    if (reqdef) {
+      if (reqdef[entdesc.origname]) {
+        transform.reqform = { [entdesc.origname]: '`reqdata`' }
+      }
+      else if (reqdef[entdesc.origname]) {
+        transform.reqform = { [entdesc.origname]: '`reqdata`' }
+      }
 
-        const op = entdesc.path[pathStr].op
+    }
 
-        op[opname] = {
-          // TODO: in actual guide, remove "standard" method ops since redundant
-          method: methodStr,
-          why_op: why_op.join(';')
-        }
+    const op = entdesc.path[pathStr].op
 
-        if (0 < Object.entries(transform).length) {
-          op[opname].transform = transform
-        }
+    op[opname] = {
+      // TODO: in actual guide, remove "standard" method ops since redundant
+      method: methodStr,
+      why_op: why_op.join(';')
+    }
 
-        // if ('/v2/users/{user_id}/enrollment' === pathStr) {
-        //   console.log('ENT')
-        //   console.dir(entdesc, { depth: null })
-        // }
-      })
+    if (0 < Object.entries(transform).length) {
+      op[opname].transform = transform
     }
+
+    // if ('/v2/users/{user_id}/enrollment' === pathStr) {
+    //   console.log('ENT')
+    //   console.dir(entdesc, { depth: null })
+    // }
+    // })
+    // }
   })
 
   // console.log('USER')
@@ -164,7 +205,7 @@ function resolveEntityDescs(ctx: any) {
 
 function resolveEntity(
   entityDescs: Record<string, EntityDesc>,
-  pathDef: Record<string, any>,
+  // pathDef: Record<string, any>,
   pathStr: string,
   methodDef: Record<string, any>,
   methodStr: string,
@@ -180,6 +221,9 @@ function resolveEntity(
   const m = pathStr.match(/\/([a-zA-Z0-1_-]+)(\/\{([a-zA-Z0-1_-]+)\})?$/)
   if (m) {
     let pathName = m[1]
+    let pathParam = m[3]
+
+
     origentname = snakify(pathName)
     entname = depluralize(origentname)
 
@@ -201,7 +245,6 @@ function resolveEntity(
       alias: {}
     })
 
-    let pathParam = m[3]
     if (null != pathParam) {
       const pathParamCanon = snakify(pathParam)
       if ('id' != pathParamCanon) {
@@ -283,94 +326,6 @@ function resolveComponentName(
     }
   }
 
-  /*
-  const responses = methodDef.responses
-  const schemalist =
-    [
-      methodDef.requestBody?.content,
-      responses?.['201'],
-      responses?.['200'],
-    ]
-      .filter(cmp => null != cmp)
-      .map(content => content['application/json']?.schema)
-      .filter(schema => null != schema)
-      // .filter(schema => null != schema['x-ref'])
-      .map(schema => {
-
-        let xrefs = find(schema, 'x-ref')
-
-        if ('responses' === pathName) {
-          console.log('xrefs', xrefs)
-        }
-
-        let xrefv = String(xrefs[0])
-
-        let xrefm = xrefv.match(/\/components\/schemas\/(.+)$/)
-        if (xrefm) {
-          schema['x-ref-cmp'] = xrefm[1]
-        }
-        return schema
-      })
-      .filter(schema => null != schema['x-ref-cmp'])
-
-  if ('responses' === pathName) {
-    console.log('CMP', pathName, schemalist.length)
-    // console.dir(methodDef.responses['200'].content['application/json'].schema, { depth: null })
-  }
-
-  let schema = undefined
-  let splen = -1
-
-  if (0 < schemalist.length) {
-    why_name.push('schema')
-  }
-
-  for (let sI = 0; sI < schemalist.length; sI++) {
-    let nextschema = schemalist[sI]
-    let nsplen = nextschema.properties?.length || -1
-
-    // console.log('QQQ', splen, nsplen, schema?.['x-ref-cmp'], nextschema?.['x-ref-cmp'])
-
-    if (
-      // More properties probably means it is the full entity.
-      splen < nsplen ||
-
-      // Shorter name probably means it is the full entity (no suffix/prefix).
-      (schema && splen === nsplen && nextschema['x-ref-cmp'].length < schema['x-ref-cmp'].length)
-
-    ) {
-      schema = nextschema
-      splen = nsplen
-    }
-  }
-
-  if (schema) {
-    let xref = schema['x-ref']
-    // console.log('RCN-XREF', methodStr, 'xref-0', xref)
-
-    if (null == xref) {
-      why_name.push('xref')
-      const properties = schema.properties || {}
-      each(properties, (prop) => {
-        if (null == xref) {
-          if (prop.type === 'array') {
-            xref = prop.items?.['x-ref']
-            // console.log('RCN', methodStr, 'xref-1', xref)
-          }
-        }
-      })
-    }
-
-    if (null != xref && 'string' === typeof xref) {
-      let xrefm = xref.match(/\/components\/schemas\/(.+)$/)
-      if (xrefm) {
-        why_name.push('cmp')
-        compname = xrefm[1]
-      }
-    }
-  }
-  */
-
   return compname
 }
 
@@ -412,74 +367,71 @@ function isListResponse(
   entdesc: EntityDesc,
   why: string[]
 ): boolean {
-  const responses = methodDef.responses
-  const resdef = responses?.['201'] || responses?.['200']
-  const content = resdef?.content
 
+  const caught = capture(methodDef, {
+    responses: {
+      '`$ANY`': { content: { 'application/json': { schema: '`$CAPTURE`' } } },
+    }
+  })
+
+  const schema = caught.schema
   let islist = false
 
-  if (null == content) {
-    // console.log('NO-CONTENT', pathStr, methodDef)
-    why.push('no-content')
+  if (null == schema) {
+    why.push('no-schema')
   }
   else {
-    const schema = content['application/json']?.schema
-    if (null == schema) {
-      why.push('no-schema')
+    if (schema.type === 'array') {
+      why.push('array')
+      islist = true
     }
-    else {
 
-      if (schema.type === 'array') {
-        why.push('array')
-        islist = true
-      }
+    if (!islist) {
+      const properties = schema.properties || {}
+      each(properties, (prop) => {
+        if (prop.type === 'array') {
 
-      if (!islist) {
-        const properties = schema.properties || {}
-        each(properties, (prop) => {
-          if (prop.type === 'array') {
-
-            if (1 === size(properties)) {
-              why.push('one-prop:' + prop.key$)
-              islist = true
-            }
-
-            if (2 === size(properties) &&
-              ('data' === prop.key$ ||
-                'list' === prop.key$)
-            ) {
-              why.push('two-prop:' + prop.key$)
-              islist = true
-            }
-
-            if (prop.key$ === entdesc.name) {
-              why.push('name:' + entdesc.origname)
-              islist = true
-            }
-
-            if (prop.key$ === entdesc.origname) {
-              why.push('origname:' + entdesc.origname)
-              islist = true
-            }
-
-            const listent = listedEntity(prop)
-            if (listent === entdesc.name) {
-              why.push('listent:' + listent)
-              islist = true
-            }
-
-
-            // if ('/v2/users' === pathStr) {
-            //   console.log('islistresponse', islist, pathStr, entdesc.name, listedEntity(prop), properties)
-            // }
+          if (1 === size(properties)) {
+            why.push('one-prop:' + prop.key$)
+            islist = true
           }
-        })
-      }
 
-      if (!islist) {
-        why.push('not-list')
-      }
+          if (2 === size(properties) &&
+            ('data' === prop.key$ ||
+              'list' === prop.key$)
+          ) {
+            why.push('two-prop:' + prop.key$)
+            islist = true
+          }
+
+          if (prop.key$ === entdesc.name) {
+            why.push('name:' + entdesc.origname)
+            islist = true
+          }
+
+          if (prop.key$ === entdesc.origname) {
+            why.push('origname:' + entdesc.origname)
+            islist = true
+          }
+
+          const listent = listedEntity(prop)
+          if (listent === entdesc.name) {
+            why.push('listent:' + listent)
+            islist = true
+          }
+
+
+          // if ('/v2/users' === pathStr) {
+          //   console.log('islistresponse', islist, pathStr, entdesc.name, listedEntity(prop), properties)
+          // }
+        }
+      })
     }
+
+    if (!islist) {
+      why.push('not-list')
+    }
+    // }
   }
 
   return islist
@@ -495,17 +447,6 @@ function listedEntity(prop: any) {
 }
 
 
-function find(obj: any, qkey: string): any[] {
-  let vals: any[] = []
-  walk(obj, (key: any, val: any, _p: any, t: string[]) => {
-    if (qkey === key) {
-      vals.push({ key, val, path: t })
-    }
-    return val
-  })
-  return vals
-}
-
 
 export {
   heuristic01

package/src/{guide.ts → guide.ts.off}

@@ -3,7 +3,7 @@ import Path from 'node:path'
 
 import { File, Content, each } from 'jostraca'
 
-import { merge } from '@voxgig/struct'
+import { merge, items } from '@voxgig/struct'
 
 
 import { heuristic01 } from './guide/heuristic01'
@@ -54,8 +54,7 @@ async function resolveGuide(ctx: any) {
   const guideBlocks = [
     '# Guide',
     '',
-    'main: api: guide: { ',
-
+    'main: api: guide: {',
   ]
 
 
@@ -64,11 +63,13 @@ async function resolveGuide(ctx: any) {
 entity: ${entityname}: {` +
       (0 < entity.why_name.length ? ' # name:' + entity.why_name.join(';') : ''))
 
-    each(entity.path, (path, pathname) => {
+    items(entity.path).map((pathn) => {
+      const [pathname, path] = pathn
       guideBlocks.push(`  path: '${pathname}': op: {` +
         (0 < path.why_ent.length ? ' # ent:' + path.why_ent.join(';') : ''))
 
-      each(path.op, (op, opname) => {
+      items(path.op).map((opn) => {
+        const [opname, op] = opn
         guideBlocks.push(`    '${opname}': method: ${op.method}` +
           (0 < op.why_op.length ? ' # ' + op.why_op : ''))
         if (op.transform?.reqform) {
@@ -87,6 +88,8 @@ entity: ${entityname}: {` +
 
   const guideSrc = guideBlocks.join('\n')
 
+  ctx.note.guide = { base: guideSrc }
+
   return () => {
     // Save base guide for reference
     File({ name: '../def/' + Path.basename(guideFile) }, () => Content(guideSrc))

package/src/resolver.ts

@@ -11,11 +11,11 @@ async function resolveElements(
   standard: Record<string, any>
 ) {
 
-  const { log, model } = ctx
+  const { log, model, guide } = ctx
 
   // TODO: model access should be via a utility that generates
   // useful errors when the target is missing
-  const control = model.main.api.guide.control[kind][subkind]
+  const control = guide.control[kind][subkind]
 
   const target = kind + '.' + subkind
 

package/src/transform/entity.ts

@@ -11,13 +11,8 @@ import { depluralize } from '../utility'
 
 const entityTransform: Transform = async function(
   ctx: any,
-  // guide: Guide,
-  // // tspec: TransformSpec,
-  // model: any,
-  // def: any
 ): Promise<TransformResult> {
-  const { apimodel, model, def } = ctx
-  const guide = model.main.api.guide
+  const { apimodel, model, def, guide } = ctx
 
   let msg = ''
 

package/src/transform/field.ts

@@ -10,13 +10,8 @@ import { fixName } from '../transform'
 
 const fieldTransform: Transform = async function(
   ctx: any,
-  // guide: Guide,
-  // // tspec: TransformSpec,
-  // model: any,
-  // def: any
 ): Promise<TransformResult> {
-  const { apimodel, model, def } = ctx
-  const guide = model.main.api.guide
+  const { apimodel, model, def, guide } = ctx
 
   let msg = 'fields: '
 

package/src/transform/operation.ts

@@ -14,8 +14,7 @@ import { depluralize } from '../utility'
 const operationTransform = async function(
   ctx: any,
 ): Promise<TransformResult> {
-  const { apimodel, model, def } = ctx
-  const guide = model.main.api.guide
+  const { apimodel, model, def, guide } = ctx
 
   let msg = 'operations: '
 

package/src/transform/top.ts

@@ -8,15 +8,9 @@ import { fixName } from '../transform'
 
 const topTransform = async function(
   ctx: any,
-  // guide: Guide,
-  // // tspec: TransformSpec,
-  // model: any,
-  // def: any
 ): Promise<TransformResult> {
   const { apimodel, def } = ctx
 
-  // const { spec } = ctx
-
   apimodel.main.def.info = def.info
   apimodel.main.def.servers = def.servers
 

package/src/types.ts

@@ -21,6 +21,20 @@ type ApiDefOptions = {
   strategy?: string
 }
 
+const ControlShape = Gubu({
+  step: {
+    parse: true,
+    guide: true,
+    transformers: true,
+    builders: true,
+    generate: true,
+  }
+})
+const OpenControlShape = Gubu(Open(ControlShape), { name: 'Control' })
+
+type Control = ReturnType<typeof ControlShape>
+
+
 
 const ModelShape = Gubu({
   name: String,
@@ -74,7 +88,22 @@ type ApiModel = {
 }
 
 
+type ApiDefResult = {
+  ok: boolean
+  start: number
+  end: number
+  steps: string[]
+  ctrl: Control
+
+  guide?: any
+  apimodel?: any
+  ctx?: any
+  jres?: any
+}
+
+
 export {
+  OpenControlShape,
   OpenModelShape,
   OpenBuildShape,
 }
@@ -84,6 +113,8 @@ export type {
   Log,
   FsUtil,
   ApiDefOptions,
+  ApiDefResult,
+  Control,
   Model,
   Build,
   ApiModel,