@voxgig/apidef 2.3.1 → 2.4.0

package/model/apidef.jsonic

@@ -1,53 +1,4 @@
 
-main: api: guide: control: {
-
-  transform: openapi: {
-    order: *`
-      top,
-      entity,
-      operation,
-      field,
-      clean,
-      ` | string,
-
-    element: {
-      top: {}
-      entity: {}
-      operation: {}
-      field: {}
-    }
-  }
-
-  builder: standard: {
-    order: *`
-      entity,
-      flow,
-      ` | string,
-
-    element: {
-      entity: {}
-      flow: {}
-    }
-  }
-
-}
-
-
-
-main: api: guide: entity: &: {
-  name: .$KEY
-  path: &: {
-    op: &: {
-      method: *'get' | string
-      transform: {
-        # TODO: make these work
-        # inward: *null | string | object
-        # outward: *null | string | object
-      }
-    }
-  }
-}
-
-
+main: api: {}
 
 

package/model/guide.jsonic

@@ -0,0 +1,53 @@
+
+guide: control: {
+
+  transform: openapi: {
+    order: *`
+      top,
+      entity,
+      operation,
+      field,
+      clean,
+      ` | string,
+
+    element: {
+      top: {}
+      entity: {}
+      operation: {}
+      field: {}
+    }
+  }
+
+  builder: standard: {
+    order: *`
+      entity,
+      flow,
+      ` | string,
+
+    element: {
+      entity: {}
+      flow: {}
+    }
+  }
+
+}
+
+
+
+guide: entity: &: {
+  name: .$KEY
+  path: &: {
+    op: &: {
+      method: *'get' | string
+      transform: {
+        # TODO: make these work
+        # inward: *null | string | object
+        # outward: *null | string | object
+      }
+    }
+  }
+}
+
+
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/apidef",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "main": "dist/apidef.js",
   "type": "commonjs",
   "types": "dist/apidef.d.ts",
@@ -40,20 +40,21 @@
   "devDependencies": {
     "@hapi/code": "^9.0.3",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "24.2.0",
+    "@types/node": "24.3.0",
     "aontu": "^0.28.0",
     "json-schema-to-ts": "^3.1.1",
-    "memfs": "^4.36.0",
+    "memfs": "^4.36.3",
     "typescript": "^5.9.2"
   },
   "dependencies": {
     "@redocly/openapi-core": "1.34.5",
-    "@voxgig/struct": "^0.0.6",
+    "@voxgig/struct": "^0.0.9",
     "@voxgig/util": "^0.2.0",
     "chokidar": "^4.0.3",
+    "diff": "^8.0.2",
     "gubu": "^9.0.0",
     "jostraca": "^0.24.1",
-    "pino": "^9.7.0",
+    "pino": "^9.9.0",
     "pino-pretty": "^13.1.1",
     "sonic-boom": "^4.2.0"
   }

package/src/apidef.ts

@@ -11,6 +11,8 @@ import { prettyPino } from '@voxgig/util'
 
 import type {
   ApiDefOptions,
+  ApiDefResult,
+  Control,
   Model,
   Build,
   ApiModel,
@@ -19,12 +21,13 @@ import type {
 import {
   OpenModelShape,
   OpenBuildShape,
+  OpenControlShape,
 } from './types'
 
 
 import {
-  resolveGuide,
-} from './guide'
+  buildGuide,
+} from './guide/guide'
 
 
 import {
@@ -72,12 +75,19 @@ function ApiDef(opts: ApiDefOptions) {
   opts.strategy = opts.strategy || 'heuristic01'
 
 
-  async function generate(spec: any) {
+  async function generate(spec: any): Promise<ApiDefResult> {
     const start = Date.now()
+    const steps: string[] = []
     // dlog('start')
 
-    const model: Model = OpenModelShape(spec.model)
-    const build: Build = OpenBuildShape(spec.build)
+    const ctrl: Control = OpenControlShape(spec.ctrl || {})
+    const model: Model = OpenModelShape(spec.model || {})
+    const build: Build = OpenBuildShape(spec.build || {})
+
+    // Step: parse (API spec).
+    if (!ctrl.step.parse) {
+      return { ok: false, steps, start, end: Date.now(), ctrl }
+    }
 
     names(model, model.name)
 
@@ -112,7 +122,9 @@ function ApiDef(opts: ApiDefOptions) {
       defpath: Path.dirname(defpath),
       model,
       apimodel,
-      def: undefined
+      guide: {},
+      def: undefined,
+      note: {}
     }
 
     const defsrc = loadFile(defpath, 'def', fs, log)
@@ -125,9 +137,24 @@ function ApiDef(opts: ApiDefOptions) {
 
     ctx.def = def
 
+    steps.push('parse')
+
+
+    // Step: guide (derive).
+    if (!ctrl.step.guide) {
+      return { ok: false, steps, start, end: Date.now(), ctrl }
+    }
+
+    const guideModel = await buildGuide(ctx)
+    ctx.guide = guideModel.guide
+
+    steps.push('guide')
 
-    const guideBuilder = await resolveGuide(ctx)
 
+    // Step: transformers (transform spec and guide into core structures).
+    if (!ctrl.step.transformers) {
+      return { ok: false, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
+    }
 
     // const transformSpec = await resolveTransforms(ctx)
     const transforms = await resolveElements(ctx, 'transform', 'openapi', {
@@ -138,11 +165,25 @@ function ApiDef(opts: ApiDefOptions) {
       clean: cleanTransform,
     })
 
+    steps.push('transformers')
+
+    // Step: builders (build generated sub models).
+    if (!ctrl.step.builders) {
+      return { ok: false, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
+    }
+
     const builders = await resolveElements(ctx, 'builder', 'standard', {
       entity: makeEntityBuilder,
       flow: makeFlowBuilder,
     })
 
+    steps.push('builders')
+
+
+    // Step: generate (generate model files).
+    if (!ctrl.step.generate) {
+      return { ok: false, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
+    }
 
     const jostraca = Jostraca({
       now: spec.now,
@@ -153,10 +194,6 @@ function ApiDef(opts: ApiDefOptions) {
     const jmodel = {}
 
     const root = () => Project({ folder: '.' }, async () => {
-      guideBuilder()
-      // entityBuilder()
-      // flowBuilder()
-
       for (let builder of builders) {
         builder()
       }
@@ -176,12 +213,21 @@ function ApiDef(opts: ApiDefOptions) {
       }
     }
 
+    steps.push('generate')
+
     log.info({ point: 'generate-end', note: 'success', break: true })
 
     return {
       ok: true,
-      name: 'apidef',
+      start,
+      end: Date.now(),
+      steps,
+      ctrl,
+
+      guide: ctx.guide,
       apimodel,
+      ctx,
+      jres,
     }
   }
 
@@ -194,8 +240,6 @@ function ApiDef(opts: ApiDefOptions) {
 ApiDef.makeBuild = async function(opts: ApiDefOptions) {
   let apidef: any = undefined
 
-  // const outprefix = null == opts.outprefix ? '' : opts.outprefix
-
   const config = {
     def: opts.def || 'no-def',
     kind: 'openapi3',
@@ -217,7 +261,9 @@ ApiDef.makeBuild = async function(opts: ApiDefOptions) {
       })
     }
 
-    return await apidef.generate({ model, build, config })
+    const ctrl = build.spec.buildargs?.apidef?.ctrl || {}
+
+    return await apidef.generate({ model, build, config, ctrl })
   }
 
   build.step = 'pre'

package/src/builder/flow/flowHeuristic01.ts

@@ -5,7 +5,7 @@ import { each, names } from 'jostraca'
 
 
 async function flowHeuristic01(ctx: any): Promise<any[]> {
-  let entity = ctx.model.main.api.guide.entity
+  let entity = ctx.guide.entity
 
   const flows: any[] = []
 

package/src/guide/guide.ts

@@ -0,0 +1,274 @@
+
+import Path from 'node:path'
+
+import { Jostraca, Project, names, File, Content, each } from 'jostraca'
+
+import { Aontu, Val, Nil, Context } from 'aontu'
+
+
+import { items } from '@voxgig/struct'
+
+
+import { heuristic01 } from './heuristic01'
+
+import {
+  getdlog,
+} from '../utility'
+
+
+// Log non-fatal wierdness.
+const dlog = getdlog('apidef', __filename)
+
+
+async function buildGuide(ctx: any): Promise<any> {
+  const errs: any[] = []
+
+  // console.log(ctx)
+  const folder = Path.resolve(ctx.opts.folder)
+  // console.log('GUIDE folder', folder)
+
+  try {
+    const basejres = await buildBaseGuide(ctx)
+  }
+  catch (err: any) {
+    errs.push(err)
+  }
+
+  handleErrors(ctx, errs)
+
+  let src = ''
+  let guidePath = Path.join(folder, 'guide',
+    (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'guide.jsonic')
+
+  try {
+    src = ctx.fs.readFileSync(guidePath, 'utf8')
+  }
+  catch (err: any) {
+    errs.push(err)
+  }
+
+  handleErrors(ctx, errs)
+
+
+  const opts = {
+    path: guidePath
+  }
+
+  const guideRoot = Aontu(src, opts)
+  errs.push(...guideRoot.err)
+
+  handleErrors(ctx, errs)
+
+
+  let genctx = new Context({ root: guideRoot })
+  const guideModel = guideRoot.gen(genctx)
+
+  errs.push(...genctx.err)
+
+  handleErrors(ctx, errs)
+
+  return guideModel
+}
+
+
+function handleErrors(ctx: any, errs: any[]) {
+  if (0 < errs.length) {
+    let topmsg: string[] = []
+    for (let err of errs) {
+      topmsg.push((err?.message?.split('\n')[0]) || '')
+      ctx.log.error({ err })
+    }
+    throw new Error('SUMMARY: ' + topmsg.join('; '))
+  }
+}
+
+
+async function buildBaseGuide(ctx: any) {
+  let baseguide: Record<string, any> = {}
+
+  if ('heuristic01' === ctx.opts.strategy) {
+    baseguide = await heuristic01(ctx)
+  }
+  else {
+    throw new Error('Unknown guide strategy: ' + ctx.opts.strategy)
+  }
+
+  const guideBlocks = [
+    '# Guide',
+    '',
+    'guide: {',
+  ]
+
+
+  items(baseguide.entity).map(([entityname, entity]: any[]) => {
+    guideBlocks.push(`
+  entity: ${entityname}: {` +
+      (0 < entity.why_name.length ? ' # name:' + entity.why_name.join(';') : ''))
+
+    items(entity.path).map(([pathname, path]: any[]) => {
+      guideBlocks.push(`    path: '${pathname}': op: {` +
+        (0 < path.why_ent.length ? ' # ent:' + path.why_ent.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) {
+          guideBlocks.push(
+            `      '${opname}': transform: reqform: ${JSON.stringify(op.transform.reqform)}`)
+        }
+      })
+
+      guideBlocks.push(`    }`)
+    })
+
+    guideBlocks.push(`  }`)
+  })
+
+  guideBlocks.push('', '}')
+
+  const guideSrc = guideBlocks.join('\n')
+
+  ctx.note.guide = { base: guideSrc }
+
+  const baseGuideFileName =
+    (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'base-guide.jsonic'
+
+  const jostraca = Jostraca({
+    folder: ctx.opts.folder + '/guide',
+    now: ctx.spec.now,
+    fs: () => ctx.fs,
+    log: ctx.log,
+  })
+
+  const root = () => Project({ folder: '.' }, async () => {
+    File({ name: baseGuideFileName }, () => Content(guideSrc))
+  })
+
+  const jres = await jostraca.generate({
+    existing: { txt: { merge: true } }
+  }, root)
+
+  return jres
+}
+
+
+/*
+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.
+
+
+  guide = cleanGuide(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) + 'base-guide.jsonic')
+
+  const guideBlocks = [
+    '# Guide',
+    '',
+    'main: api: guide: {',
+  ]
+
+
+  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)}`)
+        }
+      })
+
+      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))
+  }
+}
+
+
+function cleanGuide(guide: Record<string, any>): Record<string, any> {
+  const clean: Record<string, any> = {
+    control: guide.control,
+    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,
+      why_name: entity.why_name || [],
+      path: {}
+    }
+
+    each(entity.path, (path: any, pathname: string) => {
+      ent.path[pathname] = path
+    })
+  })
+
+  return clean
+}
+*/
+
+
+export {
+  buildGuide
+}