@voxgig/apidef 1.1.1 → 1.3.0

package/src/apidef.ts

@@ -2,12 +2,12 @@
 
 import * as Fs from 'node:fs'
 import Path from 'node:path'
-
+import { inspect } from 'node:util'
 
 import { bundleFromString, createConfig } from '@redocly/openapi-core'
 import { FSWatcher } from 'chokidar'
 import { Aontu, Context } from 'aontu'
-
+import { Gubu, Open, Any } from 'gubu'
 import { prettyPino, Pino } from '@voxgig/util'
 
 
@@ -19,88 +19,94 @@ import {
 
 
 type ApiDefOptions = {
+  def?: string
   fs?: any
   pino?: ReturnType<typeof Pino>
   debug?: boolean | string
+  folder?: string
+  meta?: Record<string, any>
+  outprefix?: string
 }
 
 
-type ApiDefSpec = {
-  def: string
-  model: string,
-  kind: string,
-  meta: Record<string, any>,
-  guide?: any
-}
+const ModelShape = Gubu({
+  def: String,
+  main: {
+    guide: {},
+    sdk: {},
+    def: {},
+    api: {},
+  }
+})
+const OpenModelShape = Gubu(Open(ModelShape))
+
+type Model = ReturnType<typeof ModelShape>
+
+
+const BuildShape = Gubu({
+  spec: {
+    base: '',
+    path: '',
+    debug: '',
+    use: {},
+    res: [],
+    require: '',
+    log: {},
+    fs: Any()
+  }
+})
+const OpenBuildShape = Gubu(Open(BuildShape))
 
+type Build = ReturnType<typeof BuildShape>
 
-function ApiDef(opts: ApiDefOptions = {}) {
+
+
+function ApiDef(opts: ApiDefOptions) {
   const fs = opts.fs || Fs
   const pino = prettyPino('apidef', opts)
 
   const log = pino.child({ cmp: 'apidef' })
 
 
-  async function watch(spec: ApiDefSpec) {
-    log.info({ point: 'watch-start' })
-    log.debug({ point: 'watch-spec', spec })
-
-    await generate(spec)
-
-    const fsw = new FSWatcher()
-
-    fsw.on('change', (...args: any[]) => {
-      log.trace({ watch: 'change', file: args[0] })
-      generate(spec)
-    })
-
-    log.trace({ watch: 'add', what: 'def', file: spec.def })
-    fsw.add(spec.def)
-
-    log.trace({ watch: 'add', what: 'guide', file: spec.guide })
-    fsw.add(spec.guide)
-  }
+  async function generate(spec: any) {
+    const start = Date.now()
 
+    const model: Model = OpenModelShape(spec.model)
+    const build: Build = OpenBuildShape(spec.build)
 
-  async function generate(spec: ApiDefSpec) {
-    const start = Date.now()
+    const buildspec = build.spec
 
-    // TODO: validate spec
+    let defpath = model.def
 
-    const defpath = Path.normalize(spec.def)
+    // TOOD: defpath should be independently defined
+    defpath = Path.join(buildspec.base, '..', 'def', defpath)
 
-    log.info({ point: 'generate-start', note: 'defpath', defpath, start })
-    log.debug({ point: 'generate-spec', spec })
+    log.info({
+      point: 'generate-start',
+      note: defpath.replace(process.cwd(), '.'), defpath, start
+    })
 
     // TODO: Validate spec
     const ctx = {
       log,
       spec,
-      guide: {},
       opts,
       util: { fixName },
-      defpath: Path.dirname(defpath)
-    }
-
-
-
-    const guide = await resolveGuide(spec, opts)
-
-    if (null == guide) {
-      return
+      defpath: Path.dirname(defpath),
+      model,
     }
 
-
-    log.debug({ point: 'guide', guide })
-
-    ctx.guide = guide
     const transformSpec = await resolveTransforms(ctx)
-    log.debug({ point: 'transform', spec: transformSpec })
+
+    log.debug({
+      point: 'transform', spec: transformSpec,
+      note: log.levelVal <= 20 ? inspect(transformSpec) : ''
+    })
 
 
     let source
     try {
-      source = fs.readFileSync(spec.def, 'utf8')
+      source = fs.readFileSync(defpath, 'utf8')
     }
     catch (err: any) {
       log.error({ read: 'fail', what: 'def', file: defpath, err })
@@ -124,7 +130,7 @@ function ApiDef(opts: ApiDefOptions = {}) {
     }
 
 
-    const model = {
+    const apimodel = {
       main: {
         api: {
           entity: {}
@@ -133,36 +139,41 @@ function ApiDef(opts: ApiDefOptions = {}) {
       },
     }
 
-    try {
-      const def = bundle.bundle.parsed
-      const processResult = await processTransforms(ctx, transformSpec, model, def)
+    const def = bundle.bundle.parsed
+    const processResult = await processTransforms(ctx, transformSpec, apimodel, def)
 
-      if (!processResult.ok) {
-        log.error({ process: 'fail', what: 'transform', result: processResult })
-        throw new Error('Transform failed: ' + processResult.msg)
-      }
-      else {
-        log.debug({ process: 'result', what: 'transform', result: processResult })
-      }
-    }
-    catch (err: any) {
-      log.error({ process: 'fail', what: 'transform', err })
-      throw err
+    if (!processResult.ok) {
+      log.error({
+        fail: 'process', point: 'transform-result',
+        result: processResult, note: processResult.msg,
+        err: processResult.results[0]?.err
+      })
+
+      return { ok: false, name: 'apidef', processResult }
     }
 
-    const modelapi = { main: { api: model.main.api } }
+    const modelapi = { main: { api: apimodel.main.api } }
     let modelSrc = JSON.stringify(modelapi, null, 2)
-    modelSrc = modelSrc.substring(1, modelSrc.length - 1)
 
-    writeChanged('api-model', spec.model, modelSrc)
+    modelSrc =
+      '# GENERATED FILE - DO NOT EDIT\n\n' +
+      modelSrc.substring(1, modelSrc.length - 1).replace(/\n  /g, '\n')
 
+    const modelPath = Path.normalize(spec.config.model)
+    // console.log('modelPath', modelPath)
+    writeChanged('api-model', modelPath, modelSrc)
 
-    const modelBasePath = Path.dirname(spec.model)
-    const defFilePath = Path.join(modelBasePath, 'def.jsonic')
+    const modelBasePath = Path.dirname(modelPath)
+    const defFilePath =
+      Path.join(modelBasePath,
+        (null == opts.outprefix ? '' : opts.outprefix) + 'def-generated.jsonic')
 
-    const modelDef = { main: { def: model.main.def } }
+    const modelDef = { main: { def: apimodel.main.def } }
     let modelDefSrc = JSON.stringify(modelDef, null, 2)
-    modelDefSrc = modelDefSrc.substring(1, modelDefSrc.length - 1)
+
+    modelDefSrc =
+      '# GENERATED FILE - DO NOT EDIT\n\n' +
+      modelDefSrc.substring(1, modelDefSrc.length - 1).replace(/\n  /g, '\n')
 
     writeChanged('def-model', defFilePath, modelDefSrc)
 
@@ -170,13 +181,13 @@ function ApiDef(opts: ApiDefOptions = {}) {
 
     return {
       ok: true,
-      model,
+      name: 'apidef',
+      apimodel,
     }
   }
 
 
-
-  function writeChanged(what: string, path: string, content: string) {
+  function writeChanged(point: string, path: string, content: string) {
     let exists = false
     let changed = false
     let action = ''
@@ -193,10 +204,12 @@ function ApiDef(opts: ApiDefOptions = {}) {
 
       changed = existingContent !== content
 
+      // console.log('WC', changed, path, existingContent, content)
+
       log.info({
-        point: 'write-' + what,
-        note: 'changed,file',
-        write: 'file', what, skip: !changed, exists, changed,
+        point: 'write-' + point,
+        note: (changed ? '' : 'not-') + 'changed ' + path,
+        write: 'file', skip: !changed, exists, changed,
         contentLength: content.length, file: path
       })
 
@@ -207,116 +220,49 @@ function ApiDef(opts: ApiDefOptions = {}) {
     }
     catch (err: any) {
       log.error({
-        fail: action, what, file: path, exists, changed,
+        fail: action, point, file: path, exists, changed,
         contentLength: content.length, err
       })
+      err.__logged__ = true
       throw err
     }
   }
 
-
-
-  async function resolveGuide(spec: any, _opts: any) {
-    if (null == spec.guide) {
-      spec.guide = spec.def + '-guide.jsonic'
-    }
-
-    const path = Path.normalize(spec.guide)
-    let src: string
-
-    let action = ''
-    let exists = false
-    try {
-
-      action = 'exists'
-      let exists = fs.existsSync(path)
-
-      log.debug({ read: 'file', what: 'guide', file: path, exists })
-
-      if (exists) {
-        action = 'read'
-        src = fs.readFileSync(path, 'utf8')
-      }
-      else {
-        src = `
-# API Specification Transform Guide
-
-@"@voxgig/apidef/model/guide.jsonic"
-
-guide: entity: {
-
+  return {
+    generate,
+  }
 }
 
-guide: control: transform: openapi: order: \`
-  top,
-  entity,
-  operation,
-  field,
-  manual,
-  \`
 
-`
-        action = 'write'
-        fs.writeFileSync(path, src)
-      }
-    }
-    catch (err: any) {
-      log.error({ fail: action, what: 'guide', file: path, exists, err })
-      throw err
-    }
-
-    const aopts = { path }
-    const root = Aontu(src, aopts)
-    const hasErr = root.err && 0 < root.err.length
-
-    if (hasErr) {
-      for (let serr of root.err) {
-        let err: any = new Error('Guide model: ' + serr.msg)
-        err.cause$ = [serr]
 
-        if ('syntax' === serr.why) {
-          err.uxmsg$ = true
-        }
+ApiDef.makeBuild = async function(opts: ApiDefOptions) {
+  let apidef: any = undefined
 
-        log.error({ fail: 'parse', point: 'guide-parse', file: path, err })
+  const outprefix = null == opts.outprefix ? '' : opts.outprefix
 
-        if (err.uxmsg$) {
-          return
-        }
-        else {
-          err.rooterrs$ = root.err
-          throw err
-        }
-      }
-    }
+  const config = {
+    def: opts.def || 'no-def',
+    kind: 'openapi3',
+    model: opts.folder ?
+      (opts.folder + '/' + outprefix + 'api-generated.jsonic') : 'no-model',
+    meta: opts.meta || {},
+  }
 
-    let genctx = new Context({ root })
-    const guide = spec.guideModel = root.gen(genctx)
+  const build = async function(model: any, build: any, ctx: any) {
 
-    // TODO: collect all errors
-    if (genctx.err && 0 < genctx.err.length) {
-      const err: any = new Error('Guide build error:\n' +
-        (genctx.err.map((pe: any) => pe.msg)).join('\n'))
-      log.error({ fail: 'build', what: 'guide', file: path, err })
-      err.errs = () => genctx.err
-      throw err
+    if (null == apidef) {
+      apidef = ApiDef({
+        ...opts,
+        pino: build.log,
+      })
     }
 
-    const pathParts = Path.parse(path)
-    spec.guideModelPath = Path.join(pathParts.dir, pathParts.name + '.json')
-
-    const updatedSrc = JSON.stringify(guide, null, 2)
-
-    writeChanged('guide-model', spec.guideModelPath, updatedSrc)
-
-    return guide
+    return await apidef.generate({ model, build, config })
   }
 
+  build.step = 'pre'
 
-  return {
-    watch,
-    generate,
-  }
+  return build
 }
 
 
@@ -324,7 +270,7 @@ guide: control: transform: openapi: order: \`
 
 export type {
   ApiDefOptions,
-  ApiDefSpec,
+  // ApiDefSpec,
 }
 
 

package/src/parse.ts

@@ -0,0 +1,36 @@
+/* Copyright (c) 2024 Voxgig, MIT License */
+
+import { bundleFromString, createConfig } from '@redocly/openapi-core'
+
+
+async function parse(kind: string, source: any) {
+  if ('OpenAPI' === kind) {
+    return parseOpenAPI(source)
+  }
+  else {
+    throw new Error('@voxgig/apidef-parse: unknown kind: ' + kind)
+  }
+}
+
+
+async function parseOpenAPI(source: any) {
+  const config = await createConfig({})
+  let bundle
+
+  bundle = await bundleFromString({
+    source,
+    config,
+    dereference: true,
+  })
+
+  // console.dir(bundle.bundle, { depth: 1 })
+
+  const def = bundle.bundle.parsed
+
+  return def
+}
+
+
+export {
+  parse
+}

package/src/transform/entity.ts

@@ -2,19 +2,28 @@
 
 import { each } from 'jostraca'
 
-import type { TransformCtx, TransformSpec } from '../transform'
+import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
 
 import { fixName } from '../transform'
 
 
-
-async function entityTransform(ctx: TransformCtx, tspec: TransformSpec, model: any, def: any) {
-  const { guide: { guide } } = ctx
+const entityTransform: Transform = async function(
+  ctx: TransformCtx,
+  guide: Guide,
+  tspec: TransformSpec,
+  model: any,
+  def: any
+): Promise<TransformResult> {
   let msg = ''
 
+  // console.log('DEF', def)
+  // console.log('GUIDE', guide)
+
   each(guide.entity, (guideEntity: any) => {
+    const entityName = guideEntity.key$
+    ctx.log.debug({ point: 'guide-entity', note: entityName })
 
-    const entityModel: any = model.main.api.entity[guideEntity.key$] = {
+    const entityModel: any = model.main.api.entity[entityName] = {
       op: {},
       field: {},
       cmd: {},
@@ -27,14 +36,19 @@ async function entityTransform(ctx: TransformCtx, tspec: TransformSpec, model: a
     fixName(entityModel, guideEntity.key$)
 
     each(guideEntity.path, (guidePath: any) => {
-      const pathdef = def.paths[guidePath.key$]
+      const path = guidePath.key$
+      const pathdef = def.paths[path]
+
+      // console.log('APIDEF FIND PATH', guidePath.key$, Object.keys(def.paths),
+      //  Object.keys(def.paths).includes(guidePath.key$))
 
       if (null == pathdef) {
-        throw new Error('APIDEF: path not found in OpenAPI: ' + guidePath.key$ +
+        throw new Error('path not found in OpenAPI: ' + path +
           ' (entity: ' + guideEntity.name + ')')
       }
 
-      guidePath.parts$ = guidePath.key$.split('/')
+      // TODO: is this needed?
+      guidePath.parts$ = path.split('/')
       guidePath.params$ = guidePath.parts$
         .filter((p: string) => p.startsWith('{'))
         .map((p: string) => p.substring(1, p.length - 1))
@@ -42,7 +56,6 @@ async function entityTransform(ctx: TransformCtx, tspec: TransformSpec, model: a
     })
 
     msg += guideEntity.name + ' '
-
   })
 
   return { ok: true, msg }

package/src/transform/field.ts

@@ -2,31 +2,35 @@
 
 import { each, getx } from 'jostraca'
 
-import type { TransformCtx, TransformSpec } from '../transform'
+import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
 
 import { fixName } from '../transform'
 
 
 
-async function fieldTransform(
+const fieldTransform: Transform = async function(
   ctx: TransformCtx,
+  guide: Guide,
   tspec: TransformSpec,
   model: any,
   def: any
-) {
-  const { guide: { guide } } = ctx
+): Promise<TransformResult> {
+
   let msg = 'fields: '
 
   each(guide.entity, (guideEntity: any) => {
+    const entityName = guideEntity.key$
+    const entityModel = model.main.api.entity[entityName]
 
-    const entityModel = model.main.api.entity[guideEntity.key$]
     let fieldCount = 0
     each(guideEntity.path, (guidePath: any) => {
-      const pathdef = def.paths[guidePath.key$]
+      const path = guidePath.key$
+      const pathdef = def.paths[path]
 
       each(guidePath.op, (op: any) => {
+        const opname = op.key$
 
-        if ('load' === op.key$) {
+        if ('load' === opname) {
           fieldCount = fieldbuild(entityModel, pathdef, op, guidePath, guideEntity, model)
         }
 
@@ -127,7 +131,7 @@ guide: transform: customField: {
 guide: entity: {
   pet: path: {
     '/pet/{petId}': {
-      op:{ load: 'get', create: 'post', save: 'put' }
+      op:{ load: 'get', create: 'post', update: 'put' }
     }
   }
   pet: test: {

package/src/transform/manual.ts

@@ -3,13 +3,20 @@ import { Jsonic } from '@jsonic/jsonic-next'
 
 import { each, getx } from 'jostraca'
 
-import type { TransformCtx, TransformSpec } from '../transform'
+import type { TransformCtx, TransformSpec, TransformResult, Transform, Guide } from '../transform'
 
 
 const { deep } = Jsonic.util
 
-async function manualTransform(ctx: TransformCtx, tspec: TransformSpec, model: any, def: any) {
-  const { guide: { guide: { manual } } } = ctx
+const manualTransform = async function(
+  ctx: TransformCtx,
+  guide: Guide,
+  tspec: TransformSpec,
+  model: any,
+  def: any
+): Promise<TransformResult> {
+
+  const { model: { main: { guide: { manual } } } } = ctx
 
   deep(model, manual)