@voxgig/apidef 8.13.0 → 8.15.0

package/src/builder/entity/entity.ts

@@ -35,7 +35,8 @@ function resolveEntity(
   each(kit.entity, ((entity: any, entityName: string) => {
     const entityFile = (null == opts.outprefix ? '' : opts.outprefix) + entityName + '.aon'
 
-    let entityJSONIC = formatJSONIC(entity).trim()
+    const { model, relations } = entityAncestorSource(entity)
+    let entityJSONIC = formatJSONIC(model).trim()
     entityJSONIC = entityJSONIC.substring(1, entityJSONIC.length - 1)
 
     const fieldAliasesSrc = fieldAliases(entity)
@@ -45,6 +46,7 @@ function resolveEntity(
       `main: ${KIT}: entity: ${entity.name}: {\n\n` +
       `  alias: field: ${fieldAliasesSrc}\n` +
       entityJSONIC +
+      relations +
       '\n\n}\n'
 
     entityFiles.push({ name: entityFile, src: entitySrc })
@@ -65,6 +67,20 @@ function resolveEntity(
   }
 }
 
+function entityAncestorSource(entity: any): { model: any, relations: string } {
+  const model = { ...entity }
+  const ancestors: string[][] = entity.relations?.ancestors ?? []
+  if (null != entity.relations) {
+    model.relations = { ...entity.relations }
+    delete model.relations.ancestors
+    if (0 === Object.keys(model.relations).length) delete model.relations
+  }
+  const chains = ancestors.map(chain => '    [' + chain.map(name =>
+    'path(' + JSON.stringify('$.main.kit.entity.' + name) + ')').join(' ') + ']')
+  return { model, relations: 0 === chains.length ? '' :
+    '\n  relations: ancestors: [\n' + chains.join('\n') + '\n  ]' }
+}
+
 
 function gcEntityFiles(
   fs: any,
@@ -126,4 +142,5 @@ function fieldAliases(_entity: any): string {
 export {
   resolveEntity,
   gcEntityFiles,
+  entityAncestorSource,
 }

package/src/builder/flow/flowHeuristic01.ts

@@ -81,11 +81,11 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
 
     let num = (i * size(apiEntity.fields) * 10)
     each(apiEntity.fields, (field) => {
-      ent[field.name] =
-        'number' === field.type ? num :
-          'boolean' === field.type ? 0 === num % 2 :
-            'object' === field.type ? {} :
-              'array' === field.type ? [] :
+      ent[field.n] =
+        'number' === field.t ? num :
+          'boolean' === field.t ? 0 === num % 2 :
+            'object' === field.t ? {} :
+              'array' === field.t ? [] :
                 's' + (num.toString(16))
       num++
     })
@@ -108,9 +108,9 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
     const point = findMainLoadPoint(entop.load)
 
     // Get additional required match properties
-    each(point?.args.params, (param: any) => {
-      if (param.required) {
-        let ancestorName = param.name
+    each(point?.g.params, (param: any) => {
+      if (param.r) {
+        let ancestorName = param.n
         let ancestorEntity = apimodel.main.api.entity[ancestorName]
 
         if (null == ancestorEntity) {
@@ -122,10 +122,10 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
           flow.model.param[`${model.NAME}_TEST_${ancestorEntity.NAME}_ENTID`] = {
             [ancestorEntity.name + '01']: ancestorEntity.NAME + '01'
           }
-          am[param.name] =
+          am[param.n] =
             `\`dm$=p.${model.NAME}_TEST_${ancestorEntity.NAME}_ENTID.${ancestorEntity.name}01\``
 
-          data[`${nom(apiEntity, 'NAME')}01`][param.name] = ancestorEntity.NAME + '01'
+          data[`${nom(apiEntity, 'NAME')}01`][param.n] = ancestorEntity.NAME + '01'
         }
       }
     })
@@ -197,7 +197,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
 
 
 function findMainLoadPoint(op: ModelOp): ModelPoint | undefined {
-  let cands = op.points.filter(a => 'id' === getelem(a.segments, -1)?.var)
+  let cands = op.points.filter(a => 'id' === getelem(a.s, -1)?.var)
   return cands[0]
 }
 
@@ -207,12 +207,12 @@ function makeUpdateData(name: string, apiEntity: any, flow: any, id: string) {
   const data = flow.model.test.entity[apiEntity.name]
 
   const dataFields =
-    each(apiEntity.field).filter(f => 'id' !== f.name && !f.name.includes('_id'))
-  const stringFields = each(dataFields).filter(f => 'string' === f.type)
+    each(apiEntity.fields).filter(f => 'id' !== f.n && !f.n.includes('_id'))
+  const stringFields = each(dataFields).filter(f => 'string' === f.t)
 
   if (0 < size(stringFields)) {
     const f = stringFields[0]
-    ud[f.name] = data[id][f.name] + '-`$WHEN`'
+    ud[f.n] = data[id][f.n] + '-`$WHEN`'
   }
 
   return ud

package/src/cli.ts

@@ -0,0 +1,341 @@
+/* Copyright (c) 2024-2026 Voxgig, MIT License */
+
+// The command-line tool. `bin/voxgig-apidef` and the standalone executable
+// entry points are shims over `main`, so the option handling and the project
+// layout live in one place and under test.
+
+import * as Fs from 'node:fs'
+import Path from 'node:path'
+import { parseArgs } from 'node:util'
+
+import { Shape, Fault } from 'shape'
+
+import { ApiDef } from './apidef'
+
+
+const Pkg = require('../package.json')
+
+const GUIDE_FILE = 'guide.aon'
+const LEGACY_GUIDE_FILE = 'guide.aontu'
+const BASE_GUIDE_FILE = 'base-guide.aon'
+
+const WATCH_INTERVAL_MS = 500
+
+
+type CliOptions = {
+  name: string
+  folder: string
+  def: string
+  prefix?: string
+  watch: boolean
+  debug?: string
+  help: boolean
+  version: boolean
+  extra?: string[]
+}
+
+
+type CliProject = {
+  root: string
+  folder: string
+  outprefix: string
+  def: string
+  model: { name: string, def: string }
+  guide: string
+  legacyguide: string
+}
+
+
+type CliIO = {
+  log: (...args: any[]) => void
+  error: (...args: any[]) => void
+}
+
+
+const CONSOLE_IO: CliIO = {
+  log: (...args: any[]) => console.log(...args),
+  error: (...args: any[]) => console.error(...args),
+}
+
+
+function usage(): string {
+  return [
+    'Usage: voxgig-apidef <name> [options]',
+    '',
+    'Build the API model for project <name> from an OpenAPI, Swagger or',
+    'GraphQL definition file.',
+    '',
+    'Options:',
+    '  -f, --folder <dir>    project folder (default: <name>)',
+    '  -d, --def <file>      the API definition file (required)',
+    '  -p, --prefix <text>   prefix for generated file names (default: <name>-)',
+    '  -w, --watch           rebuild when the definition file changes',
+    '  -g, --debug <level>   log level (debug, info, warn, error); also writes',
+    '                        the resolved definition as <def>.full.json',
+    '  -h, --help            print this help and exit',
+    '  -v, --version         print the package version and exit',
+    '',
+    'The model is written to <folder>/model, which must already hold the guide',
+    'entry file <folder>/model/guide/<prefix>' + GUIDE_FILE + ':',
+    '',
+    '  @"@voxgig/apidef/model/' + GUIDE_FILE + '"',
+    '  @"./<prefix>' + BASE_GUIDE_FILE + '"',
+  ].join('\n')
+}
+
+
+function resolveOptions(argv: string[]): CliOptions {
+  const args = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      folder: { type: 'string', short: 'f', default: '' },
+      def: { type: 'string', short: 'd', default: '' },
+      prefix: { type: 'string', short: 'p' },
+      watch: { type: 'boolean', short: 'w' },
+      debug: { type: 'string', short: 'g' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+    }
+  })
+
+  const [name, ...extra] = args.positionals
+
+  return {
+    name,
+    folder: '' === args.values.folder ? name : args.values.folder,
+    def: args.values.def,
+    prefix: args.values.prefix,
+    watch: !!args.values.watch,
+    debug: args.values.debug,
+    help: !!args.values.help,
+    version: !!args.values.version,
+    extra,
+  }
+}
+
+
+function validateOptions(rawOptions: CliOptions): CliOptions {
+  // An absent prefix defaults to <name>- later, an empty one is a valid
+  // choice, an absent debug leaves the library its own default, and `extra`
+  // is not an option at all; the shape rejects all four, so they are taken
+  // out and checked here. A positional after the name is a typo rather than
+  // a spare, and was being dropped without a word.
+  const { prefix, debug, extra, ...shaped } = rawOptions
+
+  if (null != extra && 0 < extra.length) {
+    throw new Error(
+      'Unexpected extra arguments: ' + extra.join(' ') + '\n\n' + usage())
+  }
+
+  const optShape = Shape({
+    name: Fault('The first argument should be the project name.', String),
+    folder: String,
+    def: Fault('A definition file is required: --def <file>.', String),
+    watch: Boolean,
+    help: Boolean,
+    version: Boolean,
+  })
+
+  if (null != prefix && 'string' !== typeof prefix) {
+    throw new Error('The prefix should be a string.')
+  }
+  if (null != debug && 'string' !== typeof debug) {
+    throw new Error('The debug level should be a string.')
+  }
+
+  const err: any[] = []
+  const options: CliOptions = optShape(shaped, { err })
+
+  if (err[0]) {
+    throw new Error(err[0].text)
+  }
+
+  options.prefix = prefix
+  options.debug = debug
+
+  options.def = Path.resolve(options.def)
+  const stat = Fs.statSync(options.def, { throwIfNoEntry: false })
+  if (null == stat) {
+    throw new Error('Definition file not found: ' + options.def)
+  }
+
+  return options
+}
+
+
+// A name still absolute after Path.relative is on another drive, which the
+// pipeline's <base>/../def join cannot reach.
+function defName(deffolder: string, def: string, path: typeof Path = Path): string {
+  const name = path.relative(deffolder, def)
+
+  if (path.isAbsolute(name)) {
+    throw new Error(
+      'Definition file must be on the same drive as the project folder: ' + def)
+  }
+
+  return name
+}
+
+
+// The pipeline reads the definition at <base>/../def/<model.def> and writes
+// under the output folder; both are <root>/model here, so a definition kept
+// anywhere is named relative to <root>/def.
+function resolveProject(options: CliOptions): CliProject {
+  const root = Path.resolve(options.folder)
+  const folder = Path.join(root, 'model')
+  const outprefix = null == options.prefix ? options.name + '-' : options.prefix
+  const def = Path.resolve(options.def)
+  const guidefolder = Path.join(folder, 'guide')
+
+  return {
+    root,
+    folder,
+    outprefix,
+    def,
+    model: {
+      name: options.name,
+      def: defName(Path.join(folder, '..', 'def'), def),
+    },
+    guide: Path.join(guidefolder, outprefix + GUIDE_FILE),
+    legacyguide: Path.join(guidefolder, outprefix + LEGACY_GUIDE_FILE),
+  }
+}
+
+
+// A legacy `.aontu` guide is accepted here because the guide stage migrates
+// it to `.aon` before reading it.
+function checkProject(project: CliProject): void {
+  if (Fs.existsSync(project.guide) || Fs.existsSync(project.legacyguide)) {
+    return
+  }
+
+  throw new Error(
+    'Guide entry file not found: ' + project.guide + '\n' +
+    'Create it with these two lines:\n' +
+    '  @"@voxgig/apidef/model/' + GUIDE_FILE + '"\n' +
+    '  @"./' + project.outprefix + BASE_GUIDE_FILE + '"')
+}
+
+
+// The closure makeBuild returns memoises the ApiDef instance and its logger,
+// so a watch that reuses it rebuilds the model without rebuilding those.
+async function makeRunBuild(
+  project: CliProject, options: CliOptions): Promise<() => Promise<any>> {
+  const build = await ApiDef.makeBuild({
+    folder: project.folder,
+    outprefix: project.outprefix,
+    debug: options.debug,
+  })
+
+  return () => build(project.model, { spec: { base: project.folder } }, {})
+}
+
+
+function report(result: any, project: CliProject, io: CliIO): void {
+  if (result.ok) {
+    const entities = Object.keys(result.apimodel?.main?.kit?.entity || {})
+    io.log('voxgig-apidef: ok' +
+      '  model: ' + project.folder +
+      '  entities: ' + (0 < entities.length ? entities.join(' ') : 'none'))
+  }
+  else {
+    const last = result.steps?.[result.steps.length - 1] || 'start'
+    io.error('voxgig-apidef: failed after step ' + last + ': ' +
+      (result.err?.message || 'unknown error'))
+  }
+}
+
+
+function watchDef(project: CliProject, rebuild: () => Promise<void>, io: CliIO): Promise<never> {
+  return new Promise(() => {
+    let running = false
+    let pending = false
+
+    const run = async () => {
+      if (running) {
+        pending = true
+        return
+      }
+      running = true
+      try {
+        await rebuild()
+      }
+      finally {
+        running = false
+        if (pending) {
+          pending = false
+          await run()
+        }
+      }
+    }
+
+    Fs.watchFile(project.def, { interval: WATCH_INTERVAL_MS }, () => { run() })
+    io.log('voxgig-apidef: watching ' + project.def)
+  })
+}
+
+
+async function runCli(argv: string[], io: CliIO = CONSOLE_IO): Promise<number> {
+  try {
+    let options = resolveOptions(argv)
+
+    if (options.version) {
+      io.log(Pkg.version)
+      return 0
+    }
+
+    if (options.help) {
+      io.log(usage())
+      return 0
+    }
+
+    options = validateOptions(options)
+
+    const project = resolveProject(options)
+    checkProject(project)
+
+    const runBuild = await makeRunBuild(project, options)
+
+    const result = await runBuild()
+    report(result, project, io)
+
+    if (options.watch) {
+      await watchDef(project, async () => {
+        report(await runBuild(), project, io)
+      }, io)
+    }
+
+    return result.ok ? 0 : 1
+  }
+  catch (err: any) {
+    io.error('Voxgig API Definition Error:')
+    io.error(err?.message || err)
+    return 1
+  }
+}
+
+
+function main(): void {
+  runCli(process.argv.slice(2)).then((code) => {
+    process.exitCode = code
+  })
+}
+
+
+export {
+  main,
+  runCli,
+  resolveOptions,
+  validateOptions,
+  defName,
+  resolveProject,
+  checkProject,
+  usage,
+}
+
+export type {
+  CliOptions,
+  CliProject,
+  CliIO,
+}

package/src/guide/guide.ts

@@ -54,12 +54,16 @@ function migrateLegacyGuide(fs: any, folder: string, guideprefix: string): boole
     return false
   }
 
-  const legacysrc = String(fs.readFileSync(legacyguide, 'utf8'))
-  const migrated = legacysrc
+  let migrated = String(fs.readFileSync(legacyguide, 'utf8'))
     .replace(/@"@voxgig\/apidef\/model\/guide\.aontu"/g,
       '@"@voxgig/apidef/model/guide.aon"')
-    .split('@"' + guideprefix + 'base-guide.aontu"')
-    .join('@"' + guideprefix + 'base-guide.aon"')
+
+  // The sibling include is written bare or with `./`; both name this file.
+  for (const dir of ['', './']) {
+    migrated = migrated
+      .split('@"' + dir + guideprefix + 'base-guide.aontu"')
+      .join('@"' + dir + guideprefix + 'base-guide.aon"')
+  }
 
   fs.writeFileSync(guidepath, migrated)
   try { fs.unlinkSync(legacyguide) } catch (_err: any) { }

package/src/model.ts

@@ -61,17 +61,18 @@ type ModelFieldOp = {
 
 
 type ModelField = {
-  name: string
-  type: any
-  req: boolean
+  n: string
+  h: string
+  t: any
+  r: boolean
   op: Partial<Record<OpName, ModelFieldOp>>
 
-  short?: string
+  sh?: string
 
-  readOnly?: boolean
-  writeOnly?: boolean
-  deprecated?: boolean
-  format?: string
+  ro?: boolean
+  wo?: boolean
+  de?: boolean
+  fo?: string
   union?: {
     count: number
     branches: number
@@ -80,18 +81,14 @@ type ModelField = {
 }
 
 
-// Operation argument/parameter definition.
-// `example` captures a value the spec advertises (parameter `example`,
-// the first entry of `examples`, or `schema.example`/`schema.default`).
-// Test generators use this for required params in live test setup so the
-// generated request actually satisfies the API contract.
+// `ex` holds an advertised parameter example or schema default.
 type ModelArg = {
-  name: string
-  orig: string
-  type: any
-  kind: ArgKind
-  reqd: boolean
-  example?: any
+  n: string
+  or?: string
+  t: any
+  k: ArgKind
+  r: boolean
+  ex?: any
 }
 
 
@@ -133,29 +130,30 @@ type ModelPathSegment = {
 
 
 type ModelPoint = {
-  contract?: { version: number, id: string, source: string, json: string }
-  orig: string
-  kind?: PointKind
-  graphql?: ModelGraphql
-  method: MethodName
-  segments: ModelPathSegment[]
-  rename: Partial<{
+  co?: { version: 2, id: string, source: string }
+  li?: boolean | Record<string, any>
+  o: string
+  k?: PointKind
+  gq?: ModelGraphql
+  m: MethodName
+  s: ModelPathSegment[]
+  r: Partial<{
     param: Record<string, string>
     query: Record<string, string>
     header: Record<string, string>
     cookie: Record<string, string>
   }>
-  args: Partial<{
+  g: Partial<{
     params: ModelArg[]
     query: ModelArg[]
     header: ModelArg[]
     cookie: ModelArg[]
   }>
-  transform: {
+  t: {
     req?: any
     res?: any
   }
-  select: {
+  q: {
     exist: string[]
     $action?: string
   }
@@ -173,7 +171,7 @@ type ModelEntity = {
   Name?: string
   NAME?: string
   op: ModelOpMap
-  fields: ModelField[]
+  fields: Record<string, ModelField>
   id?: {
     name: string
     field: string
@@ -197,7 +195,7 @@ type ModelEntityFlow = {
 // Per-step input cluster. Test-generators name the variables they emit by
 // reading these slots, falling back to derived defaults. All fields are
 // optional — `newFlowStep` in transform/flowstep.ts guarantees the input
-// object itself exists, so consumers don't need to null-check `step.input`.
+// object itself exists, so consumers don't need to null-check `step.i`.
 type ModelEntityFlowStepInput = {
   ref?: string
   entvar?: string
@@ -226,12 +224,13 @@ type ModelEntityFlowStepSpec = {
 
 
 type ModelEntityFlowStep = {
-  op: OpName
-  input: ModelEntityFlowStepInput
-  match: Record<string, any>
-  data: Record<string, any>
-  spec: ModelEntityFlowStepSpec[]
-  valid: ModelEntityFlowStepValidator[]
+  a?: boolean
+  o: OpName
+  i: ModelEntityFlowStepInput
+  m: Record<string, any>
+  d: Record<string, any>
+  s: ModelEntityFlowStepSpec[]
+  v: ModelEntityFlowStepValidator[]
 }