@voxgig/apidef 2.4.1 → 3.1.0

package/src/guide/guide.ts

@@ -1,31 +1,52 @@
 
-import Path from 'node:path'
 
-import { Jostraca, Project, names, File, Content, each } from 'jostraca'
+import Path from 'node:path'
 
-import { Aontu, Val, Nil, Context } from 'aontu'
+import { Jostraca, Project, File, Content, each } from 'jostraca'
 
+import { Aontu } from 'aontu'
 
-import { items } from '@voxgig/struct'
+import { items, isempty } from '@voxgig/struct'
 
 
 import { heuristic01 } from './heuristic01'
 
+
+import {
+  ApiDefContext,
+
+  Guide,
+  GuideMetrics,
+  GuideEntity,
+  GuidePath,
+  GuidePathAction,
+  GuideRenameParam,
+  GuidePathOp,
+} from '../types'
+
+
+
+
 import {
   getdlog,
+  debugpath,
+  formatJSONIC,
+  relativizePath,
 } from '../utility'
 
 
 // Log non-fatal wierdness.
 const dlog = getdlog('apidef', __filename)
 
+const aontu = new Aontu()
+
+
 
-async function buildGuide(ctx: any): Promise<any> {
+async function buildGuide(ctx: ApiDefContext): Promise<any> {
+  const log = ctx.log
   const errs: any[] = []
 
-  // console.log(ctx)
   const folder = Path.resolve(ctx.opts.folder)
-  // console.log('GUIDE folder', folder)
 
   try {
     const basejres = await buildBaseGuide(ctx)
@@ -37,11 +58,18 @@ async function buildGuide(ctx: any): Promise<any> {
   handleErrors(ctx, errs)
 
   let src = ''
-  let guidePath = Path.join(folder, 'guide',
+  let guidepath = Path.join(folder, 'guide',
     (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'guide.jsonic')
 
+  log.info({
+    point: 'generate-guide',
+    note: relativizePath(guidepath),
+    guidepath,
+  })
+
+
   try {
-    src = ctx.fs.readFileSync(guidePath, 'utf8')
+    src = ctx.fs.readFileSync(guidepath, 'utf8')
   }
   catch (err: any) {
     errs.push(err)
@@ -50,41 +78,59 @@ async function buildGuide(ctx: any): Promise<any> {
   handleErrors(ctx, errs)
 
 
-  const opts = {
-    path: guidePath
-  }
-
-  const guideRoot = Aontu(src, opts)
-  errs.push(...guideRoot.err)
+  if (0 === errs.length) {
 
-  handleErrors(ctx, errs)
+    const opts = {
+      path: guidepath,
+      fs: ctx.fs,
+      errs,
+    }
 
+    const guideModel = aontu.generate(src, opts)
+    // console.log('GUIDE-MODEL', guideModel, errs)
 
-  let genctx = new Context({ root: guideRoot })
-  const guideModel = guideRoot.gen(genctx)
+    // console.dir(guideModel, { depth: null })
 
-  errs.push(...genctx.err)
+    handleErrors(ctx, errs)
 
-  handleErrors(ctx, errs)
+    return guideModel
 
-  return guideModel
+  }
 }
 
 
 function handleErrors(ctx: any, errs: any[]) {
   if (0 < errs.length) {
-    let topmsg: string[] = []
+    const topmsg: string[] = []
+    const stacks: string[] = []
     for (let err of errs) {
-      topmsg.push((err?.message?.split('\n')[0]) || '')
-      ctx.log.error({ err })
+      err = err instanceof Error ? err :
+        err.err instanceof Error ? err.err :
+          Array.isArray(err.err) && null != err.err[0] ? err.err[0] :
+            err
+
+      const msg =
+        'string' === typeof err?.message ? err.message :
+          err instanceof Error ? err.message : '' + err
+
+      topmsg.push(msg)
+
+      stacks.push('' + err.stack)
     }
-    throw new Error('SUMMARY: ' + topmsg.join('; '))
+    const summary: any = new Error(`SUMMARY (${errs.length} errors): ` + topmsg.join(' | '))
+    summary.stack = stacks.join('\n')
+    ctx.log.error(summary)
+    summary.errs = () => errs
+    throw summary
   }
 }
 
 
-async function buildBaseGuide(ctx: any) {
-  let baseguide: Record<string, any> = {}
+
+
+
+async function buildBaseGuide(ctx: ApiDefContext) {
+  let baseguide: Guide
 
   if ('heuristic01' === ctx.opts.strategy) {
     baseguide = await heuristic01(ctx)
@@ -93,28 +139,90 @@ async function buildBaseGuide(ctx: any) {
     throw new Error('Unknown guide strategy: ' + ctx.opts.strategy)
   }
 
+  // console.dir(baseguide, { depth: null })
+
+
   const guideBlocks = [
     '# Guide',
     '',
     'guide: {',
   ]
 
+  const metrics = baseguide.metrics
+
+  // TODO: these should influence the IS_ENTCMP_METHOD_RATE etc. values
+  const epr =
+    0 < metrics.count.path ? (metrics.count.entity / metrics.count.path).toFixed(3) : -1
+  const emr =
+    0 < metrics.count.method ? (metrics.count.entity / metrics.count.method).toFixed(3) : -1
+
+  ctx.log.info({
+    point: 'metrics',
+    metrics,
+    note: `epr=${epr}  emr=${emr}  ` +
+      `(entity=${metrics.count.entity} ` +
+      `paths=${metrics.count.path} methods=${metrics.count.method})`
+  })
+
+  validateBaseBuide(ctx, baseguide)
+
+  const sw = (s: string) => ctx.opts.why?.show ? s : ''
+  const qs = (v: any) => JSON.stringify(v)
+  const qt = (v: any) => '(' + qs(v) + ')'
+
+  guideBlocks.push(`  metrics: count: entity: ${metrics.count.entity}
+  metrics: count: path: ${metrics.count.path}
+  metrics: count: method: ${metrics.count.method}`)
+
+  // NOTE: items(...) sorts the iteration elements, so the generated model code
+  // is deterministic.
+
+  items(baseguide.entity).map(([entname, entity]: [string, GuideEntity]) => {
 
-  items(baseguide.entity).map(([entityname, entity]: any[]) => {
     guideBlocks.push(`
-  entity: ${entityname}: {` +
-      (0 < entity.why_name.length ? ' # name:' + entity.why_name.join(';') : ''))
+  entity: ${entname}: {`
+      // sw(0 < entity.why_name.length ? '  # name:' + entity.why_name.join(';') : '')
+    )
+
+    // NOTE: items(...) sorts the paths
+    items(entity.path).map(([pathstr, path]: [string, GuidePath]) => {
+      debugpath(pathstr, null, 'BASE-GUIDE', entname, pathstr,
+        formatJSONIC(path, { hsepd: 0, $: true, color: true }))
+
+      guideBlocks.push(`    path: ${qs(pathstr)}: {` +
+        sw(0 < path.why_path.length ?
+          '  # ent=' + entname + ';' +
+          (entity.orig !== entname && null != entity.orig ? 'orig=' + entity.orig + ';' : '') +
+          path.why_path.join(';') : ''))
+
+      if (!isempty(path.action)) {
+        items(path.action).map(([actname, actdesc]: [string, GuidePathAction]) => {
+          guideBlocks.push(`      action: ${qs(actname)}: {}` +
+            sw(0 < actdesc.why_action.length ?
+              '  # ' + actdesc.why_action.join(';') : ''))
+        })
+      }
 
-    items(entity.path).map(([pathname, path]: any[]) => {
-      guideBlocks.push(`    path: '${pathname}': op: {` +
-        (0 < path.why_ent.length ? ' # ent:' + path.why_ent.join(';') : ''))
+      if (!isempty(path.rename?.param)) {
+        items(path.rename.param).map(([psrc, rp]: [string, GuideRenameParam]) => {
+          guideBlocks.push(`      rename: param: ${qs(psrc)}: *${qs(rp.target)}` +
+            sw(0 < rp.why_rename.length ?
+              '  # ' + rp.why_rename.join(';') : ''))
+        })
+      }
 
-      items(path.op).map(([opname, op]: any[]) => {
-        guideBlocks.push(`      '${opname}': method: ${op.method}` +
-          (0 < op.why_op.length ? ' # ' + op.why_op : ''))
-        if (op.transform?.reqform) {
+      items(path.op).map(([opname, op]: [string, GuidePathOp]) => {
+        guideBlocks.push(`      op: ${opname}: method: *${op.method}` +
+          sw(0 < op.why_op.length ? '  # ' + op.why_op : ''))
+        if (null != op.transform.req) {
           guideBlocks.push(
-            `      '${opname}': transform: reqform: ${JSON.stringify(op.transform.reqform)}`)
+            // `      op: ${opname}: transform: res: *${qt(op.transform.res)}|top`)
+            `      op: ${opname}: transform: res: *${qt(op.transform.res)}|top`)
+        }
+        if (null != op.transform.res) {
+          guideBlocks.push(
+            // `      op: ${opname}: transform: res: *${qt(op.transform.res)}|top`)
+            `      op: ${opname}: transform: res: *${qt(op.transform.res)}|top`)
         }
       })
 
@@ -128,6 +236,7 @@ async function buildBaseGuide(ctx: any) {
 
   const guideSrc = guideBlocks.join('\n')
 
+
   ctx.note.guide = { base: guideSrc }
 
   const baseGuideFileName =
@@ -152,121 +261,86 @@ async function buildBaseGuide(ctx: any) {
 }
 
 
-/*
-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) {
-    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.
+function validateBaseBuide(ctx: ApiDefContext, baseguide: any) {
+  const srcm: any = {}
 
+  // Each orig path.
+  each(ctx.def.paths, (pdef: any) => {
+    const pathStr = pdef.key$
 
-  guide = cleanGuide(guide)
+    // Each orig method.
+    each(pdef, (mdef: any) => {
+      if (mdef.key$.match(/^get|post|put|patch|delete|head|options$/i)) {
+        let key = pathStr + ' ' + mdef.key$.toUpperCase()
+        let desc = (srcm[key] = (srcm[key] || { c: 0 }))
+        desc.c++
+      }
+    })
+  })
 
+  const genm: any = {}
 
-  // 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')
-  }
+  // Each entity.
+  each(baseguide.entity, (entm: GuideEntity) => {
 
-  const guideFile =
-    Path.join(ctx.opts.folder,
-      (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'base-guide.jsonic')
+    if (isempty(entm.path)) {
+      ctx.warn({
+        note: `No paths defined for entity=${entm.name}`,
+        entm,
+      })
+    }
 
-  const guideBlocks = [
-    '# Guide',
-    '',
-    'main: api: guide: {',
-  ]
+    // Each path.
+    each(entm.path, (pathm: GuidePath, pathStr) => {
 
+      if (isempty(pathm.op)) {
+        ctx.warn({
+          note: `No operations defined for entity=${entm.name} path=${pathStr}`,
+          path: pathStr,
+          entm,
+          pathm,
+        })
+      }
 
-  guideBlocks.push(...each(baseguide.entity, (entity, entityname) => {
-    guideBlocks.push(`
-entity: ${entityname}: {` +
-      (0 < entity.why_name.length ? ' # name:' + entity.why_name.join(';') : ''))
-
-    items(entity.path).map((pathn) => {
-      const [pathname, path] = pathn
-      guideBlocks.push(`  path: '${pathname}': op: {` +
-        (0 < path.why_ent.length ? ' # ent:' + path.why_ent.join(';') : ''))
-
-      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) {
-          guideBlocks.push(
-            `    '${opname}': transform: reqform: ${JSON.stringify(op.transform.reqform)}`)
-        }
+      // Each op.
+      each(pathm.op, (odef) => {
+        let key = pathStr + ' ' + odef.method
+        let desc = (genm[key] = (genm[key] || { c: 0 }))
+        desc.c++
       })
-
-      guideBlocks.push(`  }`)
     })
+  })
 
-    guideBlocks.push(`}`)
-  }))
-
-  guideBlocks.push('}')
-
-  const guideSrc = guideBlocks.join('\n')
-
-  ctx.note.guide = { base: guideSrc }
-
-  return () => {
-    // Save base guide for reference
-    File({ name: '../def/' + Path.basename(guideFile) }, () => Content(guideSrc))
-  }
-}
-
+  const srcp = Object.keys(srcm).sort()
+    .reduce((a, k) => (a.push(k + ':c=' + srcm[k].c), a), [] as string[])
 
-function cleanGuide(guide: Record<string, any>): Record<string, any> {
-  const clean: Record<string, any> = {
-    control: guide.control,
-    entity: {}
-  }
+  const genp = Object.keys(genm).sort()
+    .reduce((a, k) => (a.push(k + ':c=' + genm[k].c), a), [] as string[])
 
-  const exclude_entity = guide.exclude?.entity?.split(',') || []
-  const include_entity = guide.include?.entity?.split(',') || []
+  // Check that all paths have been assigned to entities.
+  if (srcp.join(';') !== genp.join(';')) {
+    console.log('     ', 'SRC-PATH'.padEnd(60, ' '), 'GEN-PATH')
+    for (let i = 0, j = 0; i < srcp.length || j < genp.length; i++, j++) {
+      let srcps = srcp[i]
+      let genps = genp[j]
+      let prefix = '     '
+      if (srcps !== genps) {
+        prefix = ' *** '
 
-  each(guide.entity, (entity: any, name: string) => {
-    if (exclude_entity.includes(name)) {
-      return
-    }
-    if (exclude_entity.includes('*')) {
-      if (!include_entity.includes(name)) {
-        return
+        if (srcps === genp[j + 1]) {
+          j++
+        }
+        else if (genps === srcp[i + 1]) {
+          i++
+        }
       }
+      console.log(prefix, srcps.padEnd(60, ' '), genps)
     }
-
-    let ent: any = clean.entity[name] = clean.entity[name] = {
-      name,
-      why_name: entity.why_name || [],
-      path: {}
-    }
-
-    each(entity.path, (path: any, pathname: string) => {
-      ent.path[pathname] = path
-    })
-  })
-
-  return clean
+    throw new Error('PATH MISMATCH')
+  }
 }
-*/
 
 
 export {