@voxgig/apidef 2.4.1 → 3.0.2

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@voxgig/apidef",
-  "version": "2.4.1",
+  "version": "3.0.2",
   "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.0.2",
     "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.33.2",
+    "memfs": ">=4.51.1"
   },
   "dependencies": {
     "@redocly/openapi-core": "1.34.5",
     "@voxgig/struct": "^0.0.9",
-    "@voxgig/util": "^0.2.0",
-    "chokidar": "^4.0.3",
+    "@voxgig/util": "^0.2.1",
+    "chokidar": "^5.0.0",
+    "decircular": "^1.0.0",
     "diff": "^8.0.2",
     "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.1.0",
+    "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'
 
 
@@ -49,11 +57,17 @@ import {
 import {
   loadFile,
   getdlog,
+  makeWarner,
+  formatJSONIC,
+  writeFileSyncWarn,
 } 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 { cleanTransform } from './transform/clean'
 
@@ -66,168 +80,263 @@ 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
 
-    names(model, model.name)
+      const model: Model = OpenModelShape(spec.model || {})
+      const build: Build = OpenBuildShape(spec.build || {})
 
-    const apimodel: ApiModel = {
-      main: {
-        api: {
-          entity: {}
+      // Step: parse (API spec).
+      if (!ctrl.step.parse) {
+        return { ok: true, steps, start, end: Date.now(), ctrl }
+      }
+
+      names(model, model.name)
+
+      const apimodel: ApiModel = {
+        main: {
+          api: {},
+          [KIT]: {
+            info: {},
+            entity: {},
+            flow: {},
+          },
+          def: {},
         },
-        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: defpath.replace(process.cwd(), '.'),
+        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 }
-    }
 
-    const jostraca = Jostraca({
-      now: spec.now,
-      fs: () => fs,
-      log,
-    })
+      /*
+      const transres = await resolveElements(ctx, 'transform', 'openapi', {
+        top: topTransform,
+        entity: entityTransform,
+        operation: operationTransform,
+        args: argsTransform,
+        field: fieldTransform,
+        clean: cleanTransform,
+      })
+      */
+
+      // const transformResult = await runTransform(ctx)
+      // if (null == transformResult) {
+      //   throw new Error('Unable to run Transform.')
+      // }
 
-    const jmodel = {}
+      await topTransform(ctx)
+      await entityTransform(ctx)
+      await operationTransform(ctx)
+      await argsTransform(ctx)
+      await selectTransform(ctx)
+      await fieldTransform(ctx)
+      await cleanTransform(ctx)
 
-    const root = () => Project({ folder: '.' }, async () => {
-      for (let builder of builders) {
-        builder()
+
+      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 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 builders = [
+        await makeEntityBuilder(ctx),
+
+        // TODO: move to sdkgen
+        await makeFlowBuilder(ctx),
+      ]
+
+      steps.push('builders')
+
+
+      // Step: generate (generate model files).
+      if (!ctrl.step.generate) {
+        return { ok: true, steps, start, end: Date.now(), ctrl, guide: ctx.guide }
+      }
+
+      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 })
+
+      if (hasWarnings) {
+        writeFileSyncWarn(warn, fs, './apidef-warnings.txt',
+          warn.history.map(n => formatJSONIC(n)).join('\n\n'))
+      }
 
-    return {
-      ok: true,
-      start,
-      end: Date.now(),
-      steps,
-      ctrl,
+      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
+      })
 
-      guide: ctx.guide,
-      apimodel,
-      ctx,
-      jres,
+      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,
+      }
     }
   }
 
@@ -258,6 +367,7 @@ ApiDef.makeBuild = async function(opts: ApiDefOptions) {
         outprefix: opts.outprefix,
         strategy: opts.strategy,
         pino: build.log,
+        why: opts.why,
       })
     }
 
@@ -280,8 +390,41 @@ 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,
+} from './model'
+
 
 export {
   ApiDef,
   parse,
+  formatJSONIC,
 }

package/src/builder/entity/{apiEntity.ts → entity.ts}

@@ -6,38 +6,45 @@ import { each, File, Folder, Content } from 'jostraca'
 
 
 import type {
+  KitModel,
   ApiDefOptions,
 } from '../../types'
 
 import {
-  formatJsonSrc,
+  KIT
+} from '../../types'
+
+import {
+  formatJSONIC,
 } from '../../utility'
 
 
 
-function resolveApiEntity(
+function resolveEntity(
   apimodel: any,
   opts: ApiDefOptions,
 ) {
+  const kit: KitModel = apimodel.main[KIT]
+
   const barrel = [
     '# Entity Models\n'
   ]
 
   const entityFiles: { name: string, src: string }[] = []
 
-  each(apimodel.main.api.entity, ((entity: any, entityName: string) => {
+  each(kit.entity, ((entity: any, entityName: string) => {
     const entityFile = (null == opts.outprefix ? '' : opts.outprefix) + entityName + '.jsonic'
 
-    const entityJSON =
-      JSON.stringify(entity, null, 2)
+    let entityJSONIC = formatJSONIC(entity).trim()
+    entityJSONIC = entityJSONIC.substring(1, entityJSONIC.length - 1)
 
     const fieldAliasesSrc = fieldAliases(entity)
 
     const entitySrc =
       `# Entity: ${entity.name}\n\n` +
-      `main: api: entity: ${entity.name}: {\n\n` +
+      `main: ${KIT}: entity: ${entity.name}: {\n\n` +
       `  alias: field: ${fieldAliasesSrc}\n` +
-      formatJsonSrc(entityJSON.substring(1, entityJSON.length - 1)) +
+      entityJSONIC +
       '\n\n}\n'
 
     entityFiles.push({ name: entityFile, src: entitySrc })
@@ -45,10 +52,10 @@ function resolveApiEntity(
     barrel.push(`@"${Path.basename(entityFile)}"`)
   }))
 
-  const indexFile = (null == opts.outprefix ? '' : opts.outprefix) + 'api-entity-index.jsonic'
+  const indexFile = (null == opts.outprefix ? '' : opts.outprefix) + 'entity-index.jsonic'
 
   return function apiEntityBuilder() {
-    Folder({ name: 'api' }, () => {
+    Folder({ name: 'entity' }, () => {
       each(entityFiles, (entityFile) => {
         File({ name: entityFile.name }, () => Content(entityFile.src))
       })
@@ -56,9 +63,9 @@ function resolveApiEntity(
       File({ name: indexFile }, () => Content(barrel.join('\n')))
     })
   }
-
 }
 
+
 function fieldAliases(entity: any) {
   // HEURISTIC: id may be name_id or nameId
   const fieldAliases =
@@ -84,5 +91,5 @@ function fieldAliases(entity: any) {
 
 
 export {
-  resolveApiEntity
+  resolveEntity
 }

package/src/builder/entity/info.ts

@@ -0,0 +1,53 @@
+/* Copyright (c) 2025 Voxgig, MIT License */
+
+
+import { formatJSONIC } from '../../utility'
+
+
+import type {
+  KitModel,
+
+  ApiDefOptions,
+  ApiModel,
+} from '../../types'
+
+import {
+  KIT
+} from '../../types'
+
+import {
+  File,
+  Folder,
+  Content
+} from 'jostraca'
+
+
+function resolveInfo(
+  apimodel: any,
+  opts: ApiDefOptions,
+) {
+  const kit: KitModel = apimodel.main[KIT]
+
+  const infoFile =
+    (null == opts.outprefix ? '' : opts.outprefix) + 'api-info.jsonic'
+
+  const modelInfo = { main: { info: kit.info } }
+
+  let modelDefSrc = formatJSONIC(modelInfo)
+
+  modelDefSrc =
+    '# API Information\n\n' +
+    modelDefSrc.substring(1, modelDefSrc.length - 1).replace(/\n  /g, '\n')
+
+  return function infoBuilder() {
+    Folder({ name: 'api' }, () => {
+      File({ name: infoFile }, () => Content(modelDefSrc))
+    })
+  }
+
+}
+
+
+export {
+  resolveInfo
+}