@voxgig/apidef 2.4.1 → 3.1.0

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: { kit: { 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
+}

package/src/builder/entity.ts

@@ -1,54 +1,28 @@
 /* Copyright (c) 2025 Voxgig, MIT License */
 
-import Path from 'node:path'
-
-// import { each } from 'jostraca'
-
-
-// import type {
-//   ApiDefOptions,
-//   Log,
-//   FsUtil,
-// } from '../types'
-
-
-// import {
-//   writeChanged
-// } from '../utility'
-
 
 import {
-  resolveApiEntity
-} from './entity/apiEntity'
+  resolveEntity
+} from './entity/entity'
 
 import {
-  resolveDef
-} from './entity/def'
-
-// import {
-//   resolveSdkEntity
-// } from './entity/sdkEntity'
-
+  resolveInfo
+} from './entity/info'
 
 
 async function makeEntityBuilder(ctx: any) {
   const { apimodel, opts } = ctx
 
-  const apiEntityBuilder = resolveApiEntity(apimodel, opts)
-  const defBuilder = resolveDef(apimodel, opts)
-  // const sdkEntityBuilder = resolveSdkEntity(apimodel, opts)
+  const entityBuilder = resolveEntity(apimodel, opts)
+  const infoBuilder = resolveInfo(apimodel, opts)
 
-  return function entityBuilder() {
-    apiEntityBuilder()
-    defBuilder()
-    // sdkEntityBuilder()
+  return function fullEntityBuilder() {
+    entityBuilder()
+    infoBuilder()
   }
 }
 
 
-
-
-
 export {
   makeEntityBuilder
 }

package/src/builder/flow/flowHeuristic01.ts

@@ -3,6 +3,27 @@ import { size } from '@voxgig/struct'
 
 import { each, names } from 'jostraca'
 
+import { getelem } from '@voxgig/struct'
+
+
+import type {
+  KitModel
+} from '../../types'
+
+import {
+  KIT
+} from '../../types'
+
+import type {
+  ModelEntity,
+  ModelOp,
+  ModelAlt,
+} from '../../model'
+
+import {
+  nom
+} from '../../utility'
+
 
 async function flowHeuristic01(ctx: any): Promise<any[]> {
   let entity = ctx.guide.entity
@@ -21,10 +42,12 @@ async function flowHeuristic01(ctx: any): Promise<any[]> {
 
 function resolveBasicEntityFlow(ctx: any, entity: any) {
   const { apimodel, model } = ctx
-  const apiEntity = apimodel.main.api.entity[entity.name]
+  const kit: KitModel = apimodel.main[KIT]
+
+  const apiEntity: ModelEntity = kit.entity[entity.name]
 
   const flow: any = {
-    name: 'Basic' + apiEntity.Name + 'Flow'
+    name: 'Basic' + nom(apiEntity, 'Name') + 'Flow'
   }
 
   const refs = [
@@ -39,7 +62,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
     name: flow.name,
     active: true,
     param: {
-      [`${model.NAME}_TEST_${apiEntity.NAME}_ENTID`]: idmap,
+      [`${model.NAME}_TEST_${nom(apiEntity, 'NAME')}_ENTID`]: idmap,
       [`${model.NAME}_TEST_LIVE`]: "FALSE",
       [`${model.NAME}_TEST_EXPLAIN`]: "FALSE",
     },
@@ -56,8 +79,8 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
     const id = idmap[ref]
     const ent: any = data[id] = {}
 
-    let num = (i * size(apiEntity.field) * 10)
-    each(apiEntity.field, (field) => {
+    let num = (i * size(apiEntity.fields) * 10)
+    each(apiEntity.fields, (field) => {
       ent[field.name] =
         'number' === field.type ? num :
           'boolean' === field.type ? 0 === num % 2 :
@@ -77,11 +100,15 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
   let name
 
   const am: any = {}
+  const entop = apiEntity.op ?? {}
+
+
+  if (entop.load) {
 
-  if (apiEntity.op.load) {
+    const alt = findMainLoadAlt(entop.load)
 
     // Get additional required match properties
-    each(apiEntity.op.load.param, (param: any) => {
+    each(alt?.args.param, (param: any) => {
       if (param.required) {
         let ancestorName = param.name
         let ancestorEntity = apimodel.main.api.entity[ancestorName]
@@ -98,7 +125,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
           am[param.name] =
             `\`dm$=p.${model.NAME}_TEST_${ancestorEntity.NAME}_ENTID.${ancestorEntity.name}01\``
 
-          data[`${apiEntity.NAME}01`][param.name] = ancestorEntity.NAME + '01'
+          data[`${nom(apiEntity, 'NAME')}01`][param.name] = ancestorEntity.NAME + '01'
         }
       }
     })
@@ -111,7 +138,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
       entity: `${apiEntity.name}`,
       action: 'load',
       match: {
-        id: `\`dm$=p.${model.NAME}_TEST_${apiEntity.NAME}_ENTID.${apiEntity.name}01\``,
+        id: `\`dm$=p.${model.NAME}_TEST_${nom(apiEntity, 'NAME')}_ENTID.${apiEntity.name}01\``,
         ...am,
       },
       valid: {
@@ -122,7 +149,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
     })
   }
 
-  if (apiEntity.op.update && apiEntity.op.load) {
+  if (entop.update && entop.load) {
     num++
     name = `update_${apiEntity.name}${num}`
     const id = idmap[`${apiEntity.name}01`]
@@ -151,7 +178,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
       entity: `${apiEntity.name}`,
       action: 'load',
       match: {
-        id: `\`dm$=p.${model.NAME}_TEST_${apiEntity.NAME}_ENTID.${apiEntity.name}01\``,
+        id: `\`dm$=p.${model.NAME}_TEST_${nom(apiEntity, 'NAME')}_ENTID.${apiEntity.name}01\``,
         ...am,
       },
       valid: {
@@ -169,11 +196,18 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
 }
 
 
+function findMainLoadAlt(op: ModelOp): ModelAlt | undefined {
+  let cands = op.alts.filter(a => '{id}' === getelem(a.parts, -1))
+  return cands[0]
+}
+
+
 function makeUpdateData(name: string, apiEntity: any, flow: any, id: string) {
   const ud: any = {}
   const data = flow.model.test.entity[apiEntity.name]
 
-  const dataFields = each(apiEntity.field).filter(f => 'id' !== f.name && !f.name.includes('_id'))
+  const dataFields =
+    each(apiEntity.field).filter(f => 'id' !== f.name && !f.name.includes('_id'))
   const stringFields = each(dataFields).filter(f => 'string' === f.type)
 
   if (0 < size(stringFields)) {

package/src/builder/flow.ts

@@ -1,9 +1,20 @@
 
+// TODO: move this to sdkgen
+
+
 import Path from 'node:path'
 
 import { File, Content, Folder, each } from 'jostraca'
 
+
+import {
+  ApiDefContext,
+  KIT,
+} from '../types'
+
+
 import {
+  nom,
   formatJsonSrc,
 } from '../utility'
 
@@ -11,18 +22,44 @@ import {
 import { flowHeuristic01 } from './flow/flowHeuristic01'
 
 
-async function makeFlowBuilder(ctx: any) {
-  let flows: any[] = []
+async function makeFlowBuilder(ctx: ApiDefContext): Promise<Function> {
+  const { apimodel, opts } = ctx
+
+  const flows = apimodel.main[KIT].flow
+
+  let flowBuilder = () => {
+    ctx.warn({
+      step: 'flow',
+      note: 'Unable to generate flow definitions as flows were not resolved.'
+    })
+  }
 
+  /*
   if ('heuristic01' === ctx.opts.strategy) {
-    flows = await flowHeuristic01(ctx)
+    try {
+      flows = await flowHeuristic01(ctx)
+    }
+    catch (err: any) {
+      err.foo = { x: 1, y: [2] }
+      err.foo.z = err.foo
+      ctx.warn({
+        step: 'flow',
+        note: 'Unable to resolve flows due to unexpected error: ' + err.message,
+        err,
+      })
+      return flowBuilder
+    }
   }
   else {
-    throw new Error('Unknown guide strategy: ' + ctx.opts.strategy)
+    ctx.warn({
+      step: 'flow',
+      note: 'Unable to resolve flows: unknown guide strategy: ' + ctx.opts.strategy
+    })
+    return flowBuilder
   }
+  */
 
-
-  return function flowBuilder() {
+  flowBuilder = () => {
 
     Folder({ name: 'flow' }, () => {
       const barrel = [
@@ -33,13 +70,13 @@ async function makeFlowBuilder(ctx: any) {
         let flowfile =
           Path.join(ctx.opts.folder, 'flow',
             (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) +
-            flow.Name + '.jsonic')
+            flow.name + '.jsonic')
 
-        let flowModelSrc = formatJsonSrc(JSON.stringify(flow.model, null, 2))
+        let flowModelSrc = formatJsonSrc(JSON.stringify(flow, null, 2))
 
-        let flowsrc = `# ${flow.Name}
+        let flowsrc = `# ${nom(flow, 'Name')}
 
-main: sdk: flow: ${flow.Name}:
+main: ${KIT}: flow: ${flow.name}:
 ` + flowModelSrc
 
         barrel.push(`@"${Path.basename(flowfile)}"`)
@@ -47,11 +84,15 @@ main: sdk: flow: ${flow.Name}:
         File({ name: Path.basename(flowfile) }, () => Content(flowsrc))
       })
 
-      File({
-        name: (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'flow-index.jsonic'
-      }, () => Content(barrel.join('\n')))
+      const barrelFile = (null == ctx.opts.outprefix ? '' : ctx.opts.outprefix) + 'flow-index.jsonic'
+
+      const barrelContent = barrel.join('\n')
+
+      File({ name: barrelFile }, () => Content(barrelContent))
     })
   }
+
+  return flowBuilder
 }
 
 

package/src/def.ts

@@ -0,0 +1,91 @@
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
+
+// Consolidated definitions for OpenAPI/Swagger API definition types
+
+
+type PathDef = {
+  summary?: string
+  description?: string
+  get?: MethodDef
+  put?: MethodDef
+  post?: MethodDef
+  delete?: MethodDef
+  options?: MethodDef
+  head?: MethodDef
+  patch?: MethodDef
+  trace?: MethodDef
+  servers?: ServerDef[]
+  parameters?: ParameterDef[]
+  tags?: any
+}
+
+
+type MethodDef = {
+  tags?: string[]
+  summary?: string
+  description?: string
+  operationId?: string
+  parameters?: ParameterDef[]
+  // requestBody?: RequestBodyObject | ReferenceDef
+  // responses: Record<string, ResponseObject | ReferenceDef>
+  // callbacks?: Record<string, CallbackObject | ReferenceDef>
+  deprecated?: boolean
+  // security?: SecurityRequirementDef[]
+  servers?: ServerDef[]
+}
+
+
+type ServerDef = {
+  url: string
+  description?: string
+  variables?: Record<string, ServerVariableDef>
+}
+
+
+type ServerVariableDef = {
+  enum?: string[]
+  default: string
+  description?: string
+}
+
+
+type ParameterDef = {
+  name: string
+  in: "query" | "header" | "path" | "cookie"
+  description?: string
+  required?: boolean
+  deprecated?: boolean
+  schema?: SchemaDef
+  nullable?: boolean
+  example?: any
+  // examples?: Record<string, ExampleObject | ReferenceDef>
+}
+
+
+type SchemaDef = {
+  title?: string
+  description?: string
+  type?: string
+  format?: string
+  enum?: any[]
+  items?: SchemaDef
+  properties?: Record<string, SchemaDef>
+  required?: string[]
+  additionalProperties?: boolean | SchemaDef
+  allOf?: SchemaDef[]
+  oneOf?: SchemaDef[]
+  anyOf?: SchemaDef[]
+  nullable?: boolean
+  default?: any
+  example?: any
+}
+
+
+export type {
+  PathDef,
+  MethodDef,
+  ServerDef,
+  ServerVariableDef,
+  ParameterDef,
+  SchemaDef,
+}

package/src/desc.ts

@@ -0,0 +1,154 @@
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
+
+// Consolidated intermediate analysis types for OpenAPI definition processing
+
+import type { PathMatch } from './utility'
+import type { MethodName } from './types'
+import type { ParameterDef } from './def'
+
+
+
+// // Intermediate Guide types used during analysis
+// type GuidePathRename = {
+//   param?: Record<string, string>
+// }
+
+// type GuideOp = {
+//   method: MethodName
+// }
+
+// type GuidePath = {
+//   rename?: GuidePathRename
+//   op?: Record<string, GuideOp>
+// }
+
+
+// Component analysis description
+type CmpDesc = {
+  namedesc?: any,
+  path_rate: number,
+  method_rate: number,
+}
+
+
+// Basic method description from types.ts (renamed to avoid conflict)
+type BasicMethodDesc = {
+  name: MethodName,
+  def: Record<string, any>,
+  path: string,
+}
+
+
+// Detailed method analysis description from heuristic01.ts
+type MethodDesc = {
+  path: string
+  method: string
+  summary: string
+  tags: string[]
+  parameters: any[]
+  responses: Record<string, any>
+  requestBody: Record<string, any>
+  MethodEntity: MethodEntityDesc
+}
+
+
+// Method entity relationship analysis
+type MethodEntityDesc = {
+  ref: string
+
+  cmp: string | null
+  origcmp: string | null
+  origcmpref: string | null
+
+  why_cmp: string[]
+  cmpoccur: number
+  path_rate: number
+  method_rate: number
+  entname: string
+  why_op: string[]
+  rename: Record<string, any>
+  why_rename: Record<string, any>
+  rename_orig: string[]
+  opname: string
+  why_opname: string[]
+
+  pm?: any
+}
+
+
+// Entity analysis description
+type EntityDesc = {
+  name: string
+  origname: string
+  plural: string
+  path: Record<string, EntityPathDesc>
+  alias: Record<string, string>,
+  cmp: CmpDesc
+}
+
+
+// Entity path relationship analysis
+type EntityPathDesc = {
+  op: Record<string, any>
+  pm: PathMatch
+
+  rename: {
+    param: Record<string, string>
+  }
+  why_rename: {
+    why_param: Record<string, string[]>
+  }
+
+  action: Record<string, {
+    why_action: string[]
+  }>
+
+  why_action: Record<string, string[]>
+
+  why_ent: string[]
+  why_path: string[]
+}
+
+
+// Path analysis description
+type PathDesc = {
+  orig: string
+  method: MethodName
+  parts: string[]
+  // rename: GuidePathRename
+  rename: {
+    param?: Record<string, any>
+  }
+  // op: GuidePath["op"]
+  op: Record<string, {
+    method: any
+    transform: {
+      req?: any
+      res?: any
+    }
+  }>
+  def: {
+    parameters?: ParameterDef[]
+  }
+}
+
+
+// Operation analysis description
+type OpDesc = {
+  paths: PathDesc[]
+}
+
+
+export type {
+  //  GuidePathRename,
+  //  GuideOp,
+  //  GuidePath,
+  CmpDesc,
+  BasicMethodDesc,
+  MethodDesc,
+  MethodEntityDesc,
+  EntityDesc,
+  EntityPathDesc,
+  PathDesc,
+  OpDesc,
+}