@voxgig/apidef 2.0.0 → 2.1.0

package/src/guide/heuristic01.ts

@@ -2,12 +2,34 @@
 
 import { each, snakify, names } from 'jostraca'
 
+import { size } from '@voxgig/struct'
 
 
+import {
+  depluralize,
+  getdlog
+} from '../utility'
+
+
+type EntityDesc = {
+  name: string
+  origname: string
+  plural: string
+  path: Record<string, EntityPathDesc>
+  alias: Record<string, string>
+}
+
+
+type EntityPathDesc = {
+  op: Record<string, any>
+}
+
+// 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 entityDescs = resolveEntityDescs(ctx)
 
   // console.log('entityDescs')
@@ -18,10 +40,16 @@ async function heuristic01(ctx: any): Promise<Record<string, any>> {
     entity: entityDescs,
   }
 
+  // console.log('GUIDE')
+  // console.dir(guide, { depth: null })
+
   return guide
 }
 
 
+
+
+
 const METHOD_IDOP: Record<string, string> = {
   get: 'load',
   post: 'create',
@@ -35,191 +63,320 @@ function resolveEntityDescs(ctx: any) {
   const entityDescs: Record<string, any> = {}
   const paths = ctx.def.paths
 
-  each(paths, (pathdef, pathname) => {
-    // look for rightmmost /entname/{entid}
-    const m = pathname.match(/\/([a-zA-Z0-1_-]+)\/\{([a-zA-Z0-1_-]+)\}$/)
+  // 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) {
-      let origentname = snakify(m[1])
-      let entname = depluralize(origentname)
+      // const entdesc = resolveEntity(entityDescs, pathStr, m[1], m[2])
 
-      let entdesc = (entityDescs[entname] = entityDescs[entname] || { name: entname })
-      entdesc.plural = origentname
+      each(pathDef, (methodDef: any, methodStr: string) => {
+        methodStr = methodStr.toLowerCase()
 
-      names(entdesc, entname)
 
-      entdesc.alias = entdesc.alias || {}
+        if (!METHOD_IDOP[methodStr]) {
+          return
+        }
 
-      if ('id' != m[2]) {
-        entdesc.alias.id = m[2]
-        entdesc.alias[m[2]] = 'id'
-      }
+        const entdesc = resolveEntity(entityDescs, pathDef, pathStr, methodDef, methodStr)
 
-      entdesc.path = (entdesc.path || {})
+        if (null == entdesc) {
+          console.log(
+            'WARNING: unable to resolve entity for method ' + methodStr +
+            ' path ' + pathStr)
+          return
+        }
 
-      const op: Record<string, any> = {}
-      entdesc.path[pathname] = { op }
+        // if (pathStr.includes('courses')) {
+        //   console.log('ENTRES', pathStr, methodStr)
+        //   console.dir(ent2, { depth: null })
+        // }
+
+        let opname = resolveOpName(methodStr, methodDef, pathStr, entdesc)
+
+        if (null == opname) {
+          console.log(
+            'WARNING: unable to resolve operation for method ' + methodStr +
+            ' path ' + pathStr)
+          return
+        }
 
-      each(pathdef, (mdef, method) => {
-        const opname = METHOD_IDOP[method]
-        if (null == opname) return;
 
         const transform: Record<string, any> = {
           // reqform: '`reqdata`',
           // resform: '`body`',
         }
 
-        const resokdef = mdef.responses[200] || mdef.responses[201]
+        const resokdef = methodDef.responses[200] || methodDef.responses[201]
         const resbody = resokdef?.content?.['application/json']?.schema
         if (resbody) {
-          if (resbody[origentname]) {
-            // TODO: use quotes when @voxgig/struct updated to support them
-            // transform.resform = '`body."'+origentname+'"`'
-            transform.resform = '`body.' + origentname + '`'
+          if (resbody[entdesc.origname]) {
+            transform.resform = '`body.' + entdesc.origname + '`'
           }
-          else if (resbody[entname]) {
-            transform.resform = '`body.' + entname + '`'
+          else if (resbody[entdesc.name]) {
+            transform.resform = '`body.' + entdesc.name + '`'
           }
         }
 
-        const reqdef = mdef.requestBody?.content?.['application/json']?.schema?.properties
+        const reqdef = methodDef.requestBody?.content?.['application/json']?.schema?.properties
         if (reqdef) {
-          if (reqdef[origentname]) {
-            transform.reqform = { [origentname]: '`reqdata`' }
+          if (reqdef[entdesc.origname]) {
+            transform.reqform = { [entdesc.origname]: '`reqdata`' }
           }
-          else if (reqdef[entname]) {
-            transform.reqform = { [entname]: '`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,
+          method: methodStr,
         }
 
         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')
+  // console.dir(entityDescs.user, { depth: null })
 
-  each(paths, (pathdef, pathname) => {
-    // look for rightmmost /entname/{entid}
-    const m = pathname.match(/\/([a-zA-Z0-1_-]+)$/)
-    if (m) {
-      let origentname = snakify(m[1])
-      let entname = depluralize(origentname)
-
-      let entdesc = entityDescs[entname]
-
-      if (entdesc) {
-        entdesc.path = (entdesc.path || {})
-
-        if (pathdef.get) {
-          const op: Record<string, any> = { list: { method: 'get' } }
-          entdesc.path[pathname] = { op }
-
-          const transform: Record<string, any> = {}
-          const mdef = pathdef.get
-          const resokdef = mdef.responses[200] || mdef.responses[201]
-          const resbody = resokdef?.content?.['application/json']?.schema
-          if (resbody) {
-            if (resbody[origentname]) {
-              // TODO: use quotes when @voxgig/struct updated to support them
-              // transform.resform = '`body."'+origentname+'"`'
-              transform.resform = '`body.' + origentname + '`'
-            }
-            else if (resbody[entname]) {
-              transform.resform = '`body.' + entname + '`'
-            }
-          }
+  return entityDescs
+}
 
-          if (0 < Object.entries(transform).length) {
-            op.transform = transform
-          }
-        }
-      }
+
+function resolveEntity(
+  entityDescs: Record<string, EntityDesc>,
+  pathDef: Record<string, any>,
+  pathStr: string,
+  methodDef: Record<string, any>,
+  methodStr: string,
+): EntityDesc | undefined {
+
+  let entdesc: EntityDesc
+  let entname: string = ''
+  let origentname: string = ''
+
+  const m = pathStr.match(/\/([a-zA-Z0-1_-]+)(\/\{([a-zA-Z0-1_-]+)\})?$/)
+  if (m) {
+    let pathName = m[1]
+    origentname = snakify(pathName)
+
+    // Check schema
+    const compname = resolveComponentName(methodDef, methodStr)
+    if (compname) {
+      origentname = snakify(compname)
     }
-  })
 
-  return entityDescs
-}
+    entname = depluralize(origentname)
 
+    entdesc = (entityDescs[entname] = entityDescs[entname] || {
+      name: entname,
+      id: Math.random(),
+      alias: {}
+    })
 
-function depluralize(word: string): string {
-  if (!word || word.length === 0) {
-    return word
+    let pathParam = m[3]
+    if (null != pathParam) {
+      const pathParamCanon = snakify(pathParam)
+      if ('id' != pathParamCanon) {
+        entdesc.alias.id = pathParamCanon
+        entdesc.alias[pathParamCanon] = 'id'
+      }
+    }
   }
 
-  // Common irregular plurals
-  const irregulars: Record<string, string> = {
-    'children': 'child',
-    'men': 'man',
-    'women': 'woman',
-    'teeth': 'tooth',
-    'feet': 'foot',
-    'geese': 'goose',
-    'mice': 'mouse',
-    'people': 'person',
-    'data': 'datum',
-    'criteria': 'criterion',
-    'phenomena': 'phenomenon',
-    'indices': 'index',
-    'matrices': 'matrix',
-    'vertices': 'vertex',
-    'analyses': 'analysis',
-    'axes': 'axis',
-    'crises': 'crisis',
-    'diagnoses': 'diagnosis',
-    'oases': 'oasis',
-    'theses': 'thesis',
-    'appendices': 'appendix'
+  // Can't figure out the entity
+  else {
+    console.log('NO ENTTIY', pathStr)
+    return
   }
 
-  if (irregulars[word]) {
-    return irregulars[word]
-  }
 
-  // Rules for regular plurals (applied in order)
+  // entdesc.plural = origentname
+  entdesc.origname = origentname
 
-  // -ies -> -y (cities -> city)
-  if (word.endsWith('ies') && word.length > 3) {
-    return word.slice(0, -3) + 'y'
-  }
+  names(entdesc, entname)
+
+  entdesc.alias = entdesc.alias || {}
+
+  entdesc.path = (entdesc.path || {})
+  entdesc.path[pathStr] = entdesc.path[pathStr] || {}
+  entdesc.path[pathStr].op = entdesc.path[pathStr].op || {}
 
-  // -ves -> -f or -fe (wolves -> wolf, knives -> knife)
-  if (word.endsWith('ves')) {
-    const stem = word.slice(0, -3)
-    // Check if it should be -fe (like knife, wife, life)
-    if (['kni', 'wi', 'li'].includes(stem)) {
-      return stem + 'fe'
+  return entdesc
+}
+
+
+const REQKIND: any = {
+  get: 'res',
+  post: 'req',
+  put: 'req',
+  patch: 'req',
+}
+
+
+function resolveComponentName(
+  methodDef: Record<string, any>,
+  methodStr: string,
+): string | undefined {
+  const kind = REQKIND[methodStr]
+  let compname: string | undefined = undefined
+
+  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 xrefm = schema['x-ref'].match(/\/components\/schemas\/(.+)$/)
+        if (xrefm) {
+          schema['x-ref-cmp'] = xrefm[1]
+        }
+        return schema
+      })
+      .filter(schema => null != schema['x-ref-cmp'])
+
+  let schema = undefined
+  let splen = -1
+
+  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
     }
-    return stem + 'f'
   }
 
-  // -oes -> -o (potatoes -> potato)
-  if (word.endsWith('oes')) {
-    return word.slice(0, -2)
+  if (schema) {
+    let xref = schema['x-ref']
+    // console.log('RCN-XREF', methodStr, 'xref-0', xref)
+
+    if (null == 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) {
+        compname = xrefm[1]
+      }
+    }
   }
 
-  // -ses, -xes, -zes, -shes, -ches -> remove -es (boxes -> box)
-  if (word.endsWith('ses') || word.endsWith('xes') || word.endsWith('zes') ||
-    word.endsWith('shes') || word.endsWith('ches')) {
-    return word.slice(0, -2)
+  return compname
+}
+
+
+function resolveOpName(methodStr: string, methodDef: any, pathStr: string, entdesc: EntityDesc)
+  : string | undefined {
+
+  let opname = METHOD_IDOP[methodStr]
+  if (null == opname) return;
+
+  if ('load' === opname) {
+    const islist = isListResponse(methodDef, pathStr, entdesc)
+    opname = islist ? 'list' : opname
+
+    console.log('ISLIST', entdesc.name, methodStr, opname, pathStr)
   }
 
-  // -s -> remove -s (cats -> cat)
-  if (word.endsWith('s') && !word.endsWith('ss')) {
-    return word.slice(0, -1)
+  return opname
+}
+
+
+function isListResponse(
+  methodDef: Record<string, any>,
+  pathStr: string,
+  entdesc: EntityDesc
+): boolean {
+  const responses = methodDef.responses
+  const resdef = responses?.['201'] || responses?.['200']
+  const content = resdef?.content
+
+  let islist = false
+
+  if (null != content) {
+    const schema = content['application/json']?.schema
+    if (schema) {
+      if (schema.type === 'array') {
+        islist = true
+      }
+
+      if (!islist) {
+        const properties = schema.properties || {}
+        each(properties, (prop) => {
+          if (prop.type === 'array') {
+
+            if (
+              1 === size(properties) ||
+              prop.key$ === entdesc.name ||
+              prop.key$ === entdesc.origname ||
+              listedEntity(prop) === entdesc.name
+            ) {
+              islist = true
+            }
+
+            if ('/v2/users' === pathStr) {
+              console.log('islistresponse', islist, pathStr, entdesc.name, listedEntity(prop), properties)
+            }
+          }
+        })
+      }
+    }
   }
 
-  // If none of the rules apply, return as is
-  return word
+  return islist
 }
 
 
+function listedEntity(prop: any) {
+  const xref = prop?.items?.['x-ref']
+  const m = 'string' === typeof xref && xref.match(/^#\/components\/schemas\/(.+)$/)
+  if (m) {
+    return depluralize(snakify(m[1]))
+  }
+}
+
+
+
 export {
   heuristic01
 }

package/src/guide.ts

@@ -3,43 +3,68 @@ 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'
 
-async function resolveGuide(ctx: any) {
-  // console.log('GUIDE CTX', ctx)
 
-  let guide: Record<string, any> = ctx.model.main.api.guide
+// Log non-fatal wierdness.
+const dlog = getdlog('apidef', __filename)
+
+async function resolveGuide(ctx: any) {
+  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}: path: {`)
+  guideBlocks.push(...each(baseguide.entity, (entity, entityname) => {
+    guideBlocks.push(`
+entity: ${entityname}: {`)
 
     each(entity.path, (path, pathname) => {
-      guideBlocks.push(`  '${pathname}': op: {`)
+      guideBlocks.push(`  path: '${pathname}': op: {`)
 
       each(path.op, (op, opname) => {
         guideBlocks.push(`    '${opname}': method: ${op.method}`)
@@ -59,11 +84,9 @@ async function resolveGuide(ctx: any) {
 
   const guideSrc = guideBlocks.join('\n')
 
-  // console.log(guideSrc)
-
   return () => {
-    File({ name: Path.basename(guideFile) }, () => Content(guideSrc))
-
+    // Save base guide for reference
+    File({ name: '../def/' + Path.basename(guideFile) }, () => Content(guideSrc))
   }
 }
 
@@ -74,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) => {