@voxgig/apidef 2.4.1 → 3.0.2

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,8 +1,18 @@
 
+// TODO: move this to sdkgen
+
+
 import Path from 'node:path'
 
 import { File, Content, Folder, each } from 'jostraca'
 
+
+import {
+  ApiDefContext,
+  KIT,
+} from '../types'
+
+
 import {
   formatJsonSrc,
 } from '../utility'
@@ -11,18 +21,40 @@ import {
 import { flowHeuristic01 } from './flow/flowHeuristic01'
 
 
-async function makeFlowBuilder(ctx: any) {
+async function makeFlowBuilder(ctx: ApiDefContext): Promise<Function> {
   let flows: any[] = []
+  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 = [
@@ -39,7 +71,7 @@ async function makeFlowBuilder(ctx: any) {
 
         let flowsrc = `# ${flow.Name}
 
-main: sdk: flow: ${flow.Name}:
+main: ${KIT}: flow: ${flow.Name}:
 ` + flowModelSrc
 
         barrel.push(`@"${Path.basename(flowfile)}"`)
@@ -52,6 +84,8 @@ main: sdk: flow: ${flow.Name}:
       }, () => Content(barrel.join('\n')))
     })
   }
+
+  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,143 @@
+/* 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
+  op: GuidePath["op"]
+  def: {
+    parameters?: ParameterDef[]
+  }
+}
+
+
+// Operation analysis description
+type OpDesc = {
+  paths: PathDesc[]
+}
+
+
+export type {
+  GuidePathRename,
+  GuideOp,
+  GuidePath,
+  CmpDesc,
+  BasicMethodDesc,
+  MethodDesc,
+  MethodEntityDesc,
+  EntityDesc,
+  EntityPathDesc,
+  PathDesc,
+  OpDesc,
+}