@voxgig/sdkgen 1.3.1 → 1.3.2

package/project/.sdk/src/cmp/ts/ReadmeRef_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -272,8 +272,20 @@ ${info.desc}
 
           // Show example
           if ('load' === opname || 'remove' === opname) {
+            // The id key plus every REQUIRED match key (parent path params
+            // like page_id) — the same shape that generates <Name><Op>Match,
+            // so the example always type-checks.
+            const matchItems = opRequestShape(ent, opname).items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const arg = 0 < matchItems.length
+              ? `{ ${matchItems.map((it: any) =>
+                `${it.name}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
+              : ''
             Content(`\`\`\`ts
-const result = await client.${ent.Name}().${opname}(${idF ? `{ ${idF}: ${exampleValue(ent, ent.op && ent.op[opname], idF, ent.name + '_id')} }` : ''})
+const result = await client.${ent.Name}().${opname}(${arg})
 \`\`\`
 
 `)
@@ -286,14 +298,19 @@ const results = await client.${ent.Name}().${opname}()
 `)
           }
           else if ('create' === opname) {
+            // Members come from the SAME shape that generates
+            // <Name>CreateData: every required member must appear (the
+            // /* type */ placeholders also mark the block as an illustration
+            // for the doc gates); an all-optional create renders an empty —
+            // still assignable — literal.
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().create({
 `)
-            each(fields, (field: any) => {
-              if ('id' !== field.name && field.req) {
-                Content(`  ${field.name}: /* ${canonToType(field.type, target.name)} */,
+            createItems.map((it: any) => {
+              Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
 `)
-              }
             })
             Content(`})
 \`\`\`
@@ -301,12 +318,18 @@ const result = await client.${ent.Name}().create({
 `)
           }
           else if ('update' === opname) {
-            const updateIdLine = idF
-              ? `  ${idF}: ${exampleValue(ent, ent.op && ent.op.update, idF, ent.name + '_id')},\n`
-              : ''
+            // The id key plus every REQUIRED data member — the same shape
+            // that generates <Name>UpdateData — then the patch-fields note.
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateLines = updateItems.map((it: any) =>
+              `  ${it.name}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().update({
-${updateIdLine}  // Fields to update
+${updateLines}  // Fields to update
 })
 \`\`\`
 

package/project/.sdk/src/cmp/ts/ReadmeTopQuick_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, packageName, envName, entityIdField, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -31,7 +31,7 @@ const client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const eVar = safeVarName(eName.toLowerCase(), 'ts')
-    const opnames = Object.keys(exampleEntity.op || {})
+    const opnames = entityOps(exampleEntity)
 
     let hasCall = false
 
@@ -45,26 +45,33 @@ for (const ${eVar} of ${eVar}s) {
       hasCall = true
     }
 
-    // Find a nested entity for a more interesting example
+    // Find a nested entity for a more interesting example: one with a parent
+    // chain, an active load op of its OWN, and a required non-id load param
+    // to demonstrate (the parent key, e.g. page_id).
     const nestedEntity = Object.values(entity).find((e: any) =>
-      e.active !== false && e.ancestors && e.ancestors.length > 0
+      e.active !== false &&
+      e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+      entityOps(e).includes('load') &&
+      opRequestShape(e, 'load').items.some((it: any) =>
+        !it.optional && it.name !== entityIdField(e))
     ) as any
 
-    if (nestedEntity && opnames.includes('load')) {
+    if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
       const neVar = safeVarName(neName.toLowerCase(), 'ts')
-      const parentFields = (nestedEntity.fields || [])
-        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
-      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
       const loadOp = nestedEntity.op && nestedEntity.op.load
 
-      // Model-driven id key: only emit an id match line if the nested entity
-      // has an id-like key field.
+      // Every REQUIRED load-match key (parent keys first, own id last) — the
+      // same shape that generates <Name>LoadMatch, so the example
+      // type-checks.
       const neIdF = entityIdField(nestedEntity)
-      const neMatchLines = [`  ${parentParam}: ${exampleValue(nestedEntity, loadOp, parentParam, 'example')},`]
-      if (neIdF) {
-        neMatchLines.push(`  ${neIdF}: ${exampleValue(nestedEntity, loadOp, neIdF, 'example_id')},`)
-      }
+      const neMatchLines = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === neIdF)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+        .map((it: any) =>
+          `  ${it.name}: ${exampleValue(nestedEntity, loadOp, it.name,
+            it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`
 // Load a specific ${neName.toLowerCase()} (returns a ${neName})

package/project/.sdk/src/cmp/ts/ReadmeTopTest_ts.ts

@@ -22,15 +22,27 @@ const client = ${model.const.Name}SDK.test()
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const eVar = safeVarName(eName.toLowerCase(), 'ts')
     // Drive the test-mode example off the entity's PRIMARY op (never a
     // hardcoded `load` a create-only entity lacks).
     const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
+    // A list() result is an array — name the variable accordingly.
+    const eVar = safeVarName(eName.toLowerCase(), 'ts') +
+      ('list' === primaryOp ? 's' : '')
     const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
     const idF = entityIdField(exampleEntity)
     let arg = ''
     if ('load' === primaryOp || 'remove' === primaryOp) {
-      arg = idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, 'test01')} }` : ''
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's Match type, so the block type-checks.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      arg = 0 < items.length
+        ? `{ ${items.map((it: any) =>
+          `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
+            it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
     } else if ('create' === primaryOp || 'update' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
@@ -40,7 +52,7 @@ const client = ${model.const.Name}SDK.test()
         `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
     }
     Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
-// ${eVar} is a bare ${eName} populated with mock data
+// ${eVar} is ${'list' === primaryOp ? `an array of bare ${eName} records` : `a bare ${eName}`} populated with mock data
 console.log(${eVar})
 `)
   }

package/project/.sdk/tm/py/test/test_struct_utility.py

@@ -516,7 +516,7 @@ class TestStructUtility(unittest.TestCase):
 
     # -------------------------------------------------
     # transform tests
-    # Inputs and expected outputs: build/test/transform.jsonic
+    # Inputs and expected outputs: build/test/transform.aontu
     # -------------------------------------------------
 
     def test_transform_basic(self):

package/project/.sdk/tm/rb/Makefile

@@ -1,7 +1,9 @@
 .PHONY: test build clean publish
 
+# Run the WHOLE suite (entity, direct, utility, and readme-example tests) —
+# a single-file invocation here leaves the rest of test/ silently unrun.
 test:
-	ruby -Ilib test/exists_test.rb
+	ruby -Ilib -Itest -e 'Dir.glob("./test/*_test.rb").each { |f| require f }'
 
 build:
 	@echo "No build step for Ruby"

package/src/action/action.ts

@@ -12,14 +12,14 @@ import type {
 } from '../types'
 
 
-// Append `@"<name>.jsonic"` import lines for each name not already present in
+// Append `@"<name>.aontu"` import lines for each name not already present in
 // the index content. Checking against the accumulating result (not the
 // original) means duplicate names in the same call are added at most once.
 function appendIndexEntries(content: string, names: string[]): string {
   let out = content
 
   for (const n of names) {
-    const entry = `@"${n}.jsonic"`
+    const entry = `@"${n}.aontu"`
     if (!out.includes(entry)) {
       out += '\n' + entry
     }
@@ -34,6 +34,17 @@ const UpdateIndex = cmp(function UpdateIndex(props: any) {
 })
 
 
+// Names given to an `add` action: every positional after the subcommand is
+// a name, each possibly comma-separated — `target add ts,py,go` and
+// `target add ts py go` are equivalent (space-separated extras used to be
+// silently dropped).
+function parseAddNames(args: any[]): string[] {
+  return args.slice(2)
+    .flatMap((a: any) => 'string' === typeof a ? a.split(',') : a)
+    .filter((n: any) => null != n && '' !== n)
+}
+
+
 function loadContent(actx: ActionContext, which: string | string[]) {
   which = Array.isArray(which) ? which : [which]
 
@@ -43,7 +54,7 @@ function loadContent(actx: ActionContext, which: string | string[]) {
   const modelfolder = Path.dirname(actx.url)
 
   which.map((w: string) => {
-    const indexfile = Path.join(modelfolder, w, w + '-index.jsonic')
+    const indexfile = Path.join(modelfolder, w, w + '-index.aontu')
     const indexcontent = fs.readFileSync(indexfile, 'utf8')
     content[`${w}_index`] = indexcontent
   })
@@ -56,5 +67,6 @@ function loadContent(actx: ActionContext, which: string | string[]) {
 export {
   UpdateIndex,
   appendIndexEntries,
+  parseAddNames,
   loadContent
 }

package/src/action/feature.ts

@@ -26,6 +26,7 @@ import { SdkGenError } from '../utility'
 
 import {
   UpdateIndex,
+  parseAddNames,
   loadContent,
 } from './action'
 
@@ -52,12 +53,7 @@ async function action_feature(args: string[], actx: ActionContext): Promise<Acti
 
 
 async function cmd_feature_add(args: string[], actx: ActionContext): Promise<ActionResult> {
-
-  const features_arg = args[2]
-  const features: string[] =
-    'string' === typeof features_arg ? features_arg.split(',') : features_arg
-
-  return feature_add(features, actx)
+  return feature_add(parseAddNames(args), actx)
 }
 
 
@@ -122,10 +118,10 @@ const FeatureRoot = cmp(function FeatureRoot(props: any) {
       Folder({ name: 'model/feature' }, () => {
         Copy({
           // TODO: these paths needs to be parameterised
-          from: BASE + '/project/.sdk/model/feature/' + fname + '.jsonic',
+          from: BASE + '/project/.sdk/model/feature/' + fname + '.aontu',
           exclude: true
         })
-        File({ name: 'feature-index.jsonic' }, () => UpdateIndex({
+        File({ name: 'feature-index.aontu' }, () => UpdateIndex({
           content: ctx$.meta.content.feature_index,
           names: features,
         }))

package/src/action/target.ts

@@ -31,6 +31,7 @@ import {
 
 import {
   UpdateIndex,
+  parseAddNames,
   loadContent,
 } from './action'
 
@@ -55,11 +56,7 @@ async function action_target(args: string[], actx: ActionContext): Promise<Actio
 
 
 async function cmd_target_add(args: string[], actx: ActionContext): Promise<ActionResult> {
-  const targets_arg = args[2]
-  const targets: string[] =
-    'string' === typeof targets_arg ? targets_arg.split(',') : targets_arg
-
-  return target_add(targets, actx)
+  return target_add(parseAddNames(args), actx)
 }
 
 
@@ -124,6 +121,11 @@ const TargetRoot = cmp(function TargetRoot(props: any) {
   // const tfolder = 'node_modules/@voxgig/sdkgen/project/.sdk'
 
   Project({}, () => {
+    // Resolved names of every target in this run. The index File is
+    // re-rendered per target and the last render wins, so each render must
+    // carry all names seen so far, not just its own.
+    const tnames: string[] = []
+
     each(targets, (n) => {
       const tref = n.val$
 
@@ -134,6 +136,7 @@ const TargetRoot = cmp(function TargetRoot(props: any) {
       })
 
       const { tname, tfolder, torigname, base } = resolveTarget(tref, ctx$)
+      tnames.push(tname)
       const targetNote = tname + (tname != tref ? ' ref:' + tref : '')
 
       log.info({
@@ -145,16 +148,15 @@ const TargetRoot = cmp(function TargetRoot(props: any) {
 
       Folder({ name: 'model/target' }, () => {
         Copy({
-          from: tfolder + '/model/target/' + torigname + '.jsonic',
+          from: tfolder + '/model/target/' + torigname + '.aontu',
           // exclude: true
           replace: {
             "'BASE'": "'" + base + "'"
           }
         })
-        File({ name: 'target-index.jsonic' }, () => UpdateIndex({
+        File({ name: 'target-index.aontu' }, () => UpdateIndex({
           content: ctx$.meta.content.target_index,
-          // names: targets,
-          names: [tname]
+          names: tnames,
         }))
       })
 

package/src/cmp/Deploy.ts

@@ -7,7 +7,7 @@ import {
 
 
 // Generate the SDK root deployment Makefile from the model's per-target
-// `publish` sections (see model/sdkgen.jsonic):
+// `publish` sections (see model/sdkgen.aontu):
 //
 //   publish.tag       — git release tag `<prefix>/vX.Y.Z`; every port has
 //                       one, pushed with a token from the aql key vault
@@ -179,7 +179,7 @@ deploy-dry-${t.name}:
 
   return `# ${model.Name} SDK deployment. GENERATED by @voxgig/sdkgen — regenerated
 # on every \`npm run generate\` in .sdk/; publication details live in the
-# model (.sdk/model/target/<target>.jsonic, \`publish\` section).
+# model (.sdk/model/target/<target>.aontu, \`publish\` section).
 #
 # Every port gets a git release tag <target>/vX.Y.Z. Ports with an ACTIVE
 # registry also publish a package there. Credentials are injected at exec
@@ -218,7 +218,7 @@ TARGETS := ${targets.map((t: any) => t.name).join(' ')}
 deploy:
 \t@echo "Deployment is per-target — pick one (each upload is irreversible):"
 \t@echo "  make deploy-<target>    targets: $(TARGETS)"
-\t@echo "Registry state is set in the model (.sdk/model/target/<t>.jsonic):"
+\t@echo "Registry state is set in the model (.sdk/model/target/<t>.aontu):"
 ${targets.map((t: any) => {
     const reg = registryOf(t)
     const state = reg ? `${reg.name} ${regIsActive(reg) ? 'ACTIVE' : 'publish pending (deploy = git tag only)'}` : 'tag-only'

package/src/helpers/opShape.ts

@@ -60,20 +60,58 @@ type OpShapeItem = {
 }
 
 
-// Collect an op's params, deduped by name across all of its points.
+// Collect an op's params, deduped by name across its points.
+//
+// Points tagged with `select.$action` are sub-resource/action routes folded
+// into the op (e.g. POST .../components/{component_id}/page_access_groups on
+// the create op); they do not describe the op's canonical request payload,
+// so they are excluded — unless the op consists only of action points.
+//
+// Requiredness merges by INTERSECTION: with several alternative canonical
+// points, a param the caller must always supply is one required by every
+// point; a param only some routes use is optional in the merged shape.
+// (Union-required makes the common route untypeable — e.g. a plain
+// list-by-parent-id call failing because sibling routes' ids are demanded —
+// and steers callers into passing keys that flip runtime point dispatch to
+// the wrong route.)
 function opParams(op: any): any[] {
-  const points = op && op.points ? each(op.points) : []
-  const seen: Record<string, boolean> = {}
+  let points: any[] = op && op.points ? each(op.points) : []
+
+  const canonical = points.filter((pt: any) =>
+    null == (pt && pt.select && pt.select['$action']))
+  if (0 < canonical.length) {
+    points = canonical
+  }
+
+  const seen: Record<string, any> = {}
+  const requiredOnAll: Record<string, boolean> = {}
   const out: any[] = []
-  points.forEach((pt: any) => {
+
+  points.forEach((pt: any, pointIndex: number) => {
     const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    const requiredHere: Record<string, boolean> = {}
     params.forEach((p: any) => {
-      if (p && null != p.name && !seen[p.name]) {
-        seen[p.name] = true
-        out.push(p)
+      if (p && null != p.name) {
+        requiredHere[p.name] = false !== p.reqd
+        if (!seen[p.name]) {
+          seen[p.name] = { ...p }
+          // A param first seen on a later point was absent earlier: optional.
+          requiredOnAll[p.name] = 0 === pointIndex
+          out.push(seen[p.name])
+        }
+      }
+    })
+    Object.keys(requiredOnAll).forEach((name) => {
+      if (true !== requiredHere[name]) {
+        requiredOnAll[name] = false
       }
     })
   })
+
+  out.forEach((p: any) => {
+    p.reqd = true === requiredOnAll[p.name]
+  })
+
   return out
 }
 

package/src/sdkgen.ts

@@ -19,7 +19,7 @@ import type {
   ActionResult,
 } from './types'
 
-import { SdkGenError, requirePath, isAuthActive } from './utility'
+import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix } from './utility'
 
 import { Main } from './cmp/Main'
 import { Deploy } from './cmp/Deploy'
@@ -226,7 +226,7 @@ function SdkGen(opts: SdkGenOptions) {
 
 
   function resolveModel() {
-    const path = './model/sdk.jsonic'
+    const path = './model/sdk.aontu'
     const errs: any[] = []
 
     if (null == aontu) {
@@ -299,7 +299,7 @@ SdkGen.makeBuild = async function(opts: SdkGenOptions) {
     root: opts.root,
     def: opts.def || 'no-def',
     kind: 'openapi-3',
-    model: opts.model ? (opts.model.folder + '/api.jsonic') : 'no-model',
+    model: opts.model ? (opts.model.folder + '/api.aontu') : 'no-model',
     meta: opts.meta || {},
   }
 
@@ -432,6 +432,7 @@ export {
 
   requirePath,
   isAuthActive,
+  resolveAuthPrefix,
 
   buildIdNames,
   getMatchEntries,

package/src/utility.ts

@@ -15,7 +15,7 @@ function resolvePath(ctx$: any, path: string): any {
 // True unless the model declares auth off. Templates use this to gate
 // apikey-related code, docs, and examples for public APIs that need no
 // authentication. Two opt-outs, in priority order:
-//   1. main.kit.info.auth: false        (user-facing, set in api-info.jsonic)
+//   1. main.kit.info.auth: false        (user-facing, set in api-info.aontu)
 //   2. main.kit.config.auth.active: false
 function isAuthActive(model: any): boolean {
   const info = getModelPath(model, `main.${KIT}.info`,
@@ -28,6 +28,28 @@ function isAuthActive(model: any): boolean {
 }
 
 
+// The credential prefix for the Authorization header value, resolved in
+// priority order:
+//   1. main.kit.config.auth.prefix   (per-SDK user override)
+//   2. main.kit.info.security.prefix (spec-derived, set by apidef from the
+//      API's securityScheme — e.g. 'OAuth' for Statuspage)
+//   3. 'Bearer'                      (conventional fallback)
+// '' is a valid resolved value: it means a raw credential with no prefix
+// (e.g. an apiKey scheme in a custom header). Config generators for every
+// language target must use this instead of hardcoding 'Bearer'.
+function resolveAuthPrefix(model: any): string {
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+    { only_active: false, required: false })
+  if (null != auth && null != auth.prefix) return String(auth.prefix)
+
+  const security = getModelPath(model, `main.${KIT}.info.security`,
+    { only_active: false, required: false })
+  if (null != security && null != security.prefix) return String(security.prefix)
+
+  return 'Bearer'
+}
+
+
 function requirePath(ctx$: any, path: string, flags?: { ignore?: boolean }): any {
   const fullpath = resolvePath(ctx$, path)
   const ignore = null == flags?.ignore ? false : flags.ignore
@@ -63,5 +85,6 @@ export {
   resolvePath,
   requirePath,
   isAuthActive,
+  resolveAuthPrefix,
   SdkGenError,
 }

package/project/.sdk/model/feature/feature-index.jsonic

@@ -1,5 +0,0 @@
-# Features
-
-
-@"test.jsonic"
-@"log.jsonic"