@voxgig/apidef 2.4.1 → 3.1.0

package/model/guide.jsonic

@@ -1,50 +1,20 @@
 
-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
+  active?: boolean
+  name: key()
+
   path: &: {
-    op: &: {
-      method: *'get' | string
-      transform: {
-        # TODO: make these work
-        # inward: *null | string | object
-        # outward: *null | string | object
-      }
-    }
+    active?: boolean
+    
+     op: &: {
+       active?: boolean
+       method: string
+       
+       transform?: {
+         req?: top
+         res?: top
+       }
+     }
   }
 }
 

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@voxgig/apidef",
-  "version": "2.4.1",
+  "version": "3.1.0",
   "main": "dist/apidef.js",
   "type": "commonjs",
   "types": "dist/apidef.d.ts",
   "description": "Voxgig SDK Generator.",
   "homepage": "https://github.com/voxgig/voxgig-apidef",
   "keywords": [
-    "voxgig-apidef",
-    "voxgig-apidef"
+    "voxgig",
+    "apidef",
+    "api",
+    "sdk"
   ],
   "author": "Richard Rodger (http://richardrodger.com)",
   "repository": {
@@ -20,7 +22,7 @@
   },
   "scripts": {
     "test": "node --enable-source-maps --test \"dist-test/**/*.test.js\"",
-    "test-some": "node --enable-source-maps --test-name-pattern=\"$npm_config_pattern\" --test \"dist-test/**/*.test.js\"",
+    "test-some": "node --enable-source-maps --test-name-pattern=\"$TEST_PATTERN\" --test \"dist-test/**/*.test.js\"",
     "watch": "tsc --build src test -w",
     "build": "tsc --build src test",
     "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",
@@ -40,24 +42,25 @@
   "devDependencies": {
     "@hapi/code": "^9.0.3",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "24.3.0",
+    "@types/node": "25.2.3",
     "json-schema-to-ts": "^3.1.1",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "aontu": ">=0.28",
-    "memfs": ">=4.36.3"
+    "aontu": ">=0.35.2",
+    "memfs": ">=4.56.10"
   },
   "dependencies": {
-    "@redocly/openapi-core": "1.34.5",
+    "@redocly/openapi-core": "1.34.6",
     "@voxgig/struct": "^0.0.9",
-    "@voxgig/util": "^0.2.0",
-    "chokidar": "^4.0.3",
-    "diff": "^8.0.2",
+    "@voxgig/util": "^0.2.1",
+    "chokidar": "^5.0.0",
+    "decircular": "^1.0.0",
+    "diff": "^8.0.3",
     "gubu": "^9.0.0",
-    "jostraca": "^0.24.1",
-    "pino": "^9.9.0",
-    "pino-pretty": "^13.1.1",
-    "sonic-boom": "^4.2.0"
+    "jostraca": "^0.25.1",
+    "ordu": "^4.1.1",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3"
   }
 }

package/src/apidef.ts

@@ -1,13 +1,18 @@
 /* Copyright (c) 2024-2025 Voxgig, MIT License */
 
+
 import * as Fs from 'node:fs'
 import Path from 'node:path'
-import { inspect } from 'node:util'
 
-import { Jostraca, Project, names } from 'jostraca'
+
+import {
+  Jostraca, JostracaResult, Project, names
+} from 'jostraca'
 
 import { prettyPino } from '@voxgig/util'
 
+import decircular from 'decircular'
+
 
 import type {
   ApiDefOptions,
@@ -18,10 +23,14 @@ import type {
   ApiModel,
 } from './types'
 
+
 import {
+  KIT,
+
   OpenModelShape,
   OpenBuildShape,
   OpenControlShape,
+  ApiDefContext,
 } from './types'
 
 
@@ -32,7 +41,6 @@ import {
 
 import {
   parse,
-  rewrite,
 } from './parse'
 
 
@@ -47,14 +55,25 @@ import {
 } from './resolver'
 
 import {
+  nom,
   loadFile,
   getdlog,
+  makeWarner,
+  formatJSONIC,
+  writeFileSyncWarn,
+  relativizePath,
+  getModelPath,
 } from './utility'
 
+
 import { topTransform } from './transform/top'
 import { entityTransform } from './transform/entity'
 import { operationTransform } from './transform/operation'
+import { argsTransform } from './transform/args'
+import { selectTransform } from './transform/select'
 import { fieldTransform } from './transform/field'
+import { flowTransform } from './transform/flow'
+import { flowstepTransform } from './transform/flowstep'
 import { cleanTransform } from './transform/clean'
 
 import { makeEntityBuilder } from './builder/entity'
@@ -66,168 +85,245 @@ const dlog = getdlog('apidef', __filename)
 
 function ApiDef(opts: ApiDefOptions) {
 
-
   // TODO: gubu opts!
   const fs = opts.fs || Fs
   const pino = prettyPino('apidef', opts)
   const log = pino.child({ cmp: 'apidef' })
+  const warn = makeWarner({ point: 'warning', log })
 
   opts.strategy = opts.strategy || 'heuristic01'
 
-
   async function generate(spec: any): Promise<ApiDefResult> {
     const start = Date.now()
     const steps: string[] = []
-    // dlog('start')
 
-    const ctrl: Control = OpenControlShape(spec.ctrl || {})
-    const model: Model = OpenModelShape(spec.model || {})
-    const build: Build = OpenBuildShape(spec.build || {})
+    let ctx: ApiDefContext | undefined = undefined
+    let ctrl: Control | undefined = undefined
+    let jres: JostracaResult | undefined = undefined
 
-    // Step: parse (API spec).
-    if (!ctrl.step.parse) {
-      return { ok: false, steps, start, end: Date.now(), ctrl }
-    }
+    try {
+      ctrl = OpenControlShape(spec.ctrl || {}) as Control
+
+      const model: Model = OpenModelShape(spec.model || {})
+      const build: Build = OpenBuildShape(spec.build || {})
+
+      // Step: parse (API spec).
+      if (!ctrl.step.parse) {
+        return { ok: true, steps, start, end: Date.now(), ctrl }
+      }
 
-    names(model, model.name)
+      names(model, model.name)
 
-    const apimodel: ApiModel = {
-      main: {
-        api: {
-          entity: {}
+      const apimodel: ApiModel = {
+        main: {
+          [KIT]: {
+            info: {},
+            entity: {},
+            flow: {},
+          },
         },
-        def: {},
-      },
-    }
+      }
 
-    const buildspec = build.spec
-
-    let defpath = model.def
-
-    // TOOD: defpath should be independently defined
-    defpath = Path.join(buildspec.base, '..', 'def', defpath)
-
-    log.info({
-      point: 'generate-start',
-      note: defpath.replace(process.cwd(), '.'), defpath, start
-    })
-
-    // TODO: Validate spec
-    const ctx = {
-      fs,
-      log,
-      spec,
-      opts,
-      util: { fixName },
-      defpath: Path.dirname(defpath),
-      model,
-      apimodel,
-      guide: {},
-      def: undefined,
-      note: {}
-    }
+      const buildspec = build.spec
 
-    const defsrc = loadFile(defpath, 'def', fs, log)
+      let defpath = model.def
 
-    let def = await parse('OpenAPI', defsrc, { file: defpath })
+      // TOOD: defpath should be independently defined
+      defpath = Path.join(buildspec.base, '..', 'def', defpath)
 
-    def = rewrite(def)
+      log.info({
+        point: 'generate-start',
+        note: relativizePath(defpath),
+        defpath,
+        start
+      })
 
-    fs.writeFileSync(defpath + '.full.json', JSON.stringify(def, null, 2))
+      // TODO: Validate spec
+      ctx = {
+        fs,
+        log,
+        spec,
+        opts,
+        util: { fixName },
+        defpath: Path.dirname(defpath),
+        model,
+        apimodel,
+        guide: {},
+        def: undefined,
+        note: {},
+        warn,
+
+        // TODO: remove (moved to guide)
+        metrics: {
+          count: {
+            path: 0,
+            method: 0,
+            origcmprefs: {},
+            cmp: 0,
+            tag: 0,
+            entity: 0,
+          },
+          found: {
+            cmp: {},
+            tag: {}
+          }
+        },
 
-    ctx.def = def
+        work: {}
+      }
 
-    steps.push('parse')
+      const defsrc = loadFile(defpath, 'def', fs, log)
 
+      const def = await parse('OpenAPI', defsrc, { file: defpath })
+      const defkeys = Object.keys(def)
 
-    // Step: guide (derive).
-    if (!ctrl.step.guide) {
-      return { ok: false, steps, start, end: Date.now(), ctrl }
-    }
+      log.info({
+        point: 'root-keys',
+        defpath,
+        note: defkeys.join(', ')
+      })
 
-    const guideModel = await buildGuide(ctx)
-    ctx.guide = guideModel.guide
+      const safedef = decircular(def)
+      const fullsrc = JSON.stringify(safedef, null, 2)
 
-    steps.push('guide')
+      fs.writeFileSync(defpath + '.full.json', fullsrc)
 
+      ctx.def = safedef
 
-    // 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 }
-    }
+      steps.push('parse')
 
-    // const transformSpec = await resolveTransforms(ctx)
-    const transforms = await resolveElements(ctx, 'transform', 'openapi', {
-      top: topTransform,
-      entity: entityTransform,
-      operation: operationTransform,
-      field: fieldTransform,
-      clean: cleanTransform,
-    })
+      // Step: guide (derive).
+      if (!ctrl.step.guide) {
+        return { ok: false, steps, start, end: Date.now(), ctrl }
+      }
 
-    steps.push('transformers')
+      const guideModel = await buildGuide(ctx)
+      if (null == guideModel) {
+        throw new Error('Unable to build guide.')
+      }
 
-    // Step: builders (build generated sub models).
-    if (!ctrl.step.builders) {
-      return { ok: false, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
-    }
+      ctx.guide = guideModel.guide
 
-    const builders = await resolveElements(ctx, 'builder', 'standard', {
-      entity: makeEntityBuilder,
-      flow: makeFlowBuilder,
-    })
+      steps.push('guide')
 
-    steps.push('builders')
 
+      // Step: transformers (transform spec and guide into core structures).
+      if (!ctrl.step.transformers) {
+        return { ok: true, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
+      }
 
-    // Step: generate (generate model files).
-    if (!ctrl.step.generate) {
-      return { ok: false, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
-    }
+      await topTransform(ctx)
+      await entityTransform(ctx)
+      await operationTransform(ctx)
+      await argsTransform(ctx)
+      await selectTransform(ctx)
+      await fieldTransform(ctx)
+      await flowTransform(ctx)
+      await flowstepTransform(ctx)
+      await cleanTransform(ctx)
+
+      steps.push('transformers')
+
+      // Step: builders (build generated sub models).
+      if (!ctrl.step.builders) {
+        return { ok: true, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
+      }
+
+      const builders = [
+        await makeEntityBuilder(ctx),
+
+        // TODO: move to sdkgen
+        await makeFlowBuilder(ctx),
+      ]
 
-    const jostraca = Jostraca({
-      now: spec.now,
-      fs: () => fs,
-      log,
-    })
+      steps.push('builders')
 
-    const jmodel = {}
 
-    const root = () => Project({ folder: '.' }, async () => {
-      for (let builder of builders) {
-        builder()
+      // Step: generate (generate model files).
+      if (!ctrl.step.generate) {
+        return { ok: true, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
       }
-    })
-
-    const jres = await jostraca.generate({
-      // folder: Path.dirname(opts.folder as string),
-      folder: opts.folder,
-      model: jmodel,
-      existing: { txt: { merge: true } }
-    }, root)
-
-    const dlogs = dlog.log()
-    if (0 < dlogs.length) {
-      for (let dlogentry of dlogs) {
-        log.debug({ point: 'generate-warning', dlogentry, note: String(dlogentry) })
+
+      const jostraca = Jostraca({
+        now: spec.now,
+        fs: () => fs,
+        log,
+      })
+
+      const jmodel = {}
+
+      const root = () => Project({ folder: '.' }, async () => {
+        for (let builder of builders) {
+          builder()
+        }
+      })
+
+      jres = await jostraca.generate({
+        // folder: Path.dirname(opts.folder as string),
+        folder: opts.folder,
+        model: jmodel,
+        existing: { txt: { merge: true } }
+      }, root)
+
+      const dlogs = dlog.log()
+      if (0 < dlogs.length) {
+        for (let dlogentry of dlogs) {
+          log.debug({ point: 'generate-debug', dlogentry, note: String(dlogentry) })
+        }
       }
-    }
 
-    steps.push('generate')
+      steps.push('generate')
 
-    log.info({ point: 'generate-end', note: 'success', break: true })
+      const hasWarnings = 0 < warn.history.length
+      const endnote =
+        hasWarnings ? `PARTIAL BUILD! There were ${warn.history.length} warnings (see above).` :
+          'success'
+      log[hasWarnings ? 'warn' : 'info']({ point: 'generate-end', note: endnote, break: true })
 
-    return {
-      ok: true,
-      start,
-      end: Date.now(),
-      steps,
-      ctrl,
+      if (hasWarnings) {
+        writeFileSyncWarn(warn, fs, './apidef-warnings.txt',
+          warn.history.map(n => formatJSONIC(n)).join('\n\n'))
+      }
 
-      guide: ctx.guide,
-      apimodel,
-      ctx,
-      jres,
+      return {
+        ok: true,
+        err: null,
+        start,
+        end: Date.now(),
+        steps,
+        ctrl,
+        guide: ctx.guide,
+        apimodel: ctx.apimodel,
+        ctx,
+        jres,
+      }
+    }
+    catch (err: any) {
+      const endnote = '!! BUILD FAILED !! ' + err.message
+      log.error({ point: 'generate-end', err, note: endnote, break: true })
+
+      warn.history.push({
+        point: warn.point,
+        when: Date.now(),
+        err,
+        note: endnote
+      })
+
+      writeFileSyncWarn(warn, fs, './apidef-warnings.txt',
+        warn.history.map(n => formatJSONIC(n)).join('\n\n'))
+
+      return {
+        ok: false,
+        err,
+        start,
+        end: Date.now(),
+        steps,
+        ctrl,
+        guide: ctx?.guide,
+        apimodel: ctx?.apimodel,
+        ctx,
+        jres,
+      }
     }
   }
 
@@ -246,7 +342,7 @@ ApiDef.makeBuild = async function(opts: ApiDefOptions) {
     meta: opts.meta || {},
   }
 
-  const build = async function(model: any, build: any, ctx: any) {
+  const build = async function(model: any, build: any, _ctx: any) {
 
     if (null == apidef) {
       apidef = ApiDef({
@@ -258,6 +354,7 @@ ApiDef.makeBuild = async function(opts: ApiDefOptions) {
         outprefix: opts.outprefix,
         strategy: opts.strategy,
         pino: build.log,
+        why: opts.why,
       })
     }
 
@@ -280,8 +377,47 @@ export type {
   ApiDefOptions,
 }
 
+export type {
+  PathDef,
+  MethodDef,
+  ServerDef,
+  ServerVariableDef,
+  ParameterDef,
+  SchemaDef,
+} from './def'
+
+export type {
+  CmpDesc,
+  BasicMethodDesc,
+  MethodDesc,
+  MethodEntityDesc,
+  EntityDesc,
+  EntityPathDesc,
+  PathDesc,
+  OpDesc,
+} from './desc'
+
+export type {
+  OpName,
+  ModelEntityRelations,
+  ModelOpMap,
+  ModelFieldOp,
+  ModelField,
+  ModelArg,
+  ModelAlt,
+  ModelOp,
+  ModelEntity,
+  Model,
+  ModelEntityFlow,
+  ModelEntityFlowStep,
+} from './model'
+
 
 export {
+  KIT,
   ApiDef,
   parse,
+  formatJSONIC,
+  getModelPath,
+  nom,
 }