@voxgig/sdkgen 1.2.1 → 1.3.2

package/project/.sdk/src/cmp/js/utility_js.ts

@@ -2,12 +2,68 @@
 import * as Path from 'node:path'
 
 
+import {
+  canonKey,
+  each,
+} from '@voxgig/sdkgen'
+
 import {
   clone,
   walk,
 } from '@voxgig/struct'
 
 
+// --- Model-driven example literals -----------------------------------------
+// Doc snippets must use example values whose TYPE matches the generated
+// types, or the snippet misrepresents the API. The id/match params of
+// load/remove/update are the common trap: their generated
+// `<Name><Op>Match` / `<Name><Op>Data` type is built from the op's params
+// (see EntityTypes_js.ts), so a numeric id shown as a quoted string is
+// wrong. These helpers derive the example literal from the SAME model
+// source, so the docs and the generated types can never disagree.
+
+// The declared canon-type sentinel of a named parameter of an op — looked up
+// in the op's `points[].args.params[]` exactly as the typed-model generator
+// does. Falls back to the entity field of the same name (used when the op
+// has no params). Returns undefined when neither is present.
+function paramCanonType(entity: any, op: any, paramName: string): unknown {
+  const points = op && op.points ? each(op.points) : []
+  for (const pt of points as any[]) {
+    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    const found = (params as any[]).find((p: any) => p && p.name === paramName)
+    if (found) {
+      return found.type
+    }
+  }
+  const field = (entity && entity.fields ? each(entity.fields) : [])
+    .find((f: any) => f && f.name === paramName) as any
+  return field && field.type
+}
+
+
+// A type-correct example literal for a named match/data parameter of an op,
+// derived entirely from the model. INTEGER/NUMBER render as the bare number
+// `1`, BOOLEAN as `true`, ARRAY as the empty `[]` and OBJECT as the empty
+// `{}`, everything else (STRING, unknown, missing) as the quoted
+// `placeholder`.
+function exampleValue(entity: any, op: any, paramName: string, placeholder: string): string {
+  const key = canonKey(paramCanonType(entity, op, paramName))
+  if ('INTEGER' === key || 'NUMBER' === key) {
+    return '1'
+  }
+  if ('BOOLEAN' === key) {
+    return 'true'
+  }
+  if ('ARRAY' === key) {
+    return '[]'
+  }
+  if ('OBJECT' === key) {
+    return '{}'
+  }
+  return `'${placeholder}'`
+}
+
+
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
 }
@@ -61,4 +117,5 @@ export {
   formatJSONSrc,
   formatJson,
   projectPath,
+  exampleValue,
 }

package/project/.sdk/src/cmp/lua/Config_lua.ts

@@ -10,6 +10,7 @@ import {
   cmp,
   each,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -39,8 +40,8 @@ const Config = cmp(async function Config(props: any) {
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  let authPrefix = ''
-  try { authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`) } catch (_e) { }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }

package/project/.sdk/src/cmp/lua/EntityTypes_lua.ts

@@ -0,0 +1,113 @@
+
+
+// Typed-model generator (Lua target).
+//
+// Lua is dynamically typed, so the "types" are LuaLS annotations
+// (---@class / ---@field) for editor/tooling DX only — no runtime effect.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file, <sdk>_types.lua,
+// with a `---@class <Name>` per active entity plus a request/match ---@class
+// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned
+// into LuaLS types by the shared sdkgen helper `canonToType` ('lua' column).
+//
+// Keeps the SAME type-name scheme as the TS reference (<Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch). The op fragments reference these class names via
+// ---@param / ---@return.
+
+import {
+  cmp, each,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'lua'
+
+
+// A bare LuaLS field key, or a bracketed string literal for anything that is
+// not a plain Lua identifier.
+function propKey(name: string): string {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : '[' + JSON.stringify(name) + ']'
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  File({ name: model.name + '_types.' + (target.ext || LANG) }, () => {
+
+    Content(`-- Typed models for the ${model.const.Name} SDK (LuaLS annotations).
+--
+-- GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+-- params (op.<name>.points[].args.params[]). Field/param types come from the
+-- canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+-- @voxgig/apidef VALID_CANON). Annotations only — no runtime effect. Do not
+-- edit by hand.
+
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one ---@field per field, `req:false` -> optional (?).
+      Content(`---@class ${Name}
+`)
+      fields.forEach((f: any) => {
+        const opt = false === f.req ? '?' : ''
+        Content(`---@field ${propKey(f.name)}${opt} ${canonToType(f.type, LANG)}
+`)
+      })
+      Content(`
+`)
+
+      // Per active op: a request/match class. Members and their optionality
+      // come from the shared partiality policy (opRequestShape); this file only
+      // renders them as LuaLS ---@field lines.
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        Content(`---@class ${typeName}
+`)
+        items.forEach((it: any) => {
+          const opt = it.optional ? '?' : ''
+          Content(`---@field ${propKey(it.name)}${opt} ${canonToType(it.type, LANG)}
+`)
+        })
+        Content(`
+`)
+      })
+    })
+
+    // Make the file a require-able (empty) module. The blank line above keeps
+    // LuaLS from binding the last ---@class to this local.
+    Content(`local M = {}
+
+return M
+`)
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/lua/MainEntity_lua.ts

@@ -8,8 +8,16 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { model } = props.ctx$
 
   Content(`
+-- Idiomatic facade: client:${entity.Name}():list() / client:${entity.Name}():load({ id = ... })
+-- Entity access is capitalised (PascalCase) for parity with the other SDKs.
 function ${model.const.Name}SDK:${entity.Name}(data)
   local EntityMod = require("entity.${entity.name}_entity")
+  if data == nil then
+    if self._${entity.name} == nil then
+      self._${entity.name} = EntityMod.new(self, nil)
+    end
+    return self._${entity.name}
+  end
   return EntityMod.new(self, data)
 end
 

package/project/.sdk/src/cmp/lua/Main_lua.ts

@@ -22,6 +22,7 @@ import { Package } from './Package_lua'
 import { Config } from './Config_lua'
 import { Gitignore } from './Gitignore_lua'
 import { MainEntity } from './MainEntity_lua'
+import { EntityTypes } from './EntityTypes_lua'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -79,6 +80,9 @@ self._utility.feature_hook(self._rootctx, "${name}")
       })
   })
 
+  // Generate typed-model annotations (LuaLS ---@class / ---@field)
+  EntityTypes({ target })
+
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })

package/project/.sdk/src/cmp/lua/Package_lua.ts

@@ -4,6 +4,9 @@ import {
   File,
   cmp,
   collectDeps,
+  pkgDescription,
+  keywords,
+  repoInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -24,23 +27,39 @@ const Package = cmp(async function Package(props: any) {
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const rockName = `${ns}-${pkgBase}`
+  const { repoUrl, issuesUrl } = repoInfo(model)
+  const labels = keywords(model).map((k) => `"${k}"`).join(', ')
+
+  // Single source for the version so the rockspec version and the source.tag
+  // (which `make publish` pushes as lua/v<rockVersion>) can never drift apart.
+  const rockVersion = '0.0.1'
 
   File({ name: model.name + '.rockspec' }, () => {
     Content(`package = "${rockName}"
-version = "0.0-1"
+version = "${rockVersion}-1"
 source = {
-  url = "git://github.com/${ns}/${model.name}-sdk.git"
+  -- git+https (GitHub dropped git:// in 2022); pin the install to the release
+  -- tag pushed by \`make publish\`, and point at the lua/ subdir of the monorepo.
+  url = "git+https://github.com/${ns}/${model.name}-sdk.git",
+  tag = "lua/v${rockVersion}",
+  dir = "${model.name}-sdk/lua"
 }
 description = {
-  summary = "${model.const.Name} SDK for Lua",
-  license = "MIT"
+  summary = "${pkgDescription(model, 'lua')}",
+  homepage = "${repoUrl}",
+  issues_url = "${issuesUrl}",
+  license = "MIT",
+  labels = { ${labels} }
 }
 dependencies = {
   "lua >= 5.3",
   "dkjson >= 2.5",
 `)
 
+    const seen = new Set<string>(['lua', 'dkjson'])
     for (const d of collectDeps(model, target.name, target.deps)) {
+      if (seen.has(d.name)) continue
+      seen.add(d.name)
       const v = d.source === 'target' ? (d.version || '0.0') : d.version
       Content(`  "${d.name} >= ${v}",
 `)

package/project/.sdk/src/cmp/lua/ReadmeEntity_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,24 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, executable Lua literal for a param: numeric/boolean/table
+// params render a typed literal; strings render the quoted placeholder (the
+// doc test EXECUTES runnable blocks, so a comment placeholder would not
+// parse).
+function luaLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k || 'OBJECT' === k) return '{}'
+  return `"${placeholder}"`
+}
+
+// Non-identifier table keys use bracket syntax.
+function luaKey(name: string): string {
+  return /^[A-Za-z_]\w*$/.test(name) ? name : `["${name}"]`
+}
+
+
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
 // methods with optional ctrl. The op descriptions are language-agnostic.
@@ -41,6 +59,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +73,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`local ${entity.name} = client:${entity.Name}(nil)\`
 
 `)
 
@@ -84,7 +104,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -93,10 +113,22 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, 'load').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 loadArg = 0 < loadItems.length
+        ? `{ ${loadItems.map((it: any) =>
+          `${luaKey(it.name)} = ${luaLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
       Content(`#### Example: Load
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`lua
+local ${entity.name}, err = client:${entity.Name}():load(${loadArg})
 \`\`\`
 
 `)
@@ -105,24 +137,29 @@ const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_
     if (opnames.includes('list')) {
       Content(`#### Example: List
 
-\`\`\`ts
-const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`lua
+local ${entity.name}s, err = client:${entity.Name}():list()
 \`\`\`
 
 `)
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real, executable
+      // literal (the doc test RUNS this block, so a nil member would vanish
+      // from the table and a comment placeholder would not parse).
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().create({
+\`\`\`lua
+local ${entity.name}, err = client:${entity.Name}():create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+      createItems.map((it: any) => {
+        Content(`  ${luaKey(it.name)} = ${luaLit(it.type, 'example_' + it.name)}, -- ${canonToType(it.type, target.name)}
 `)
-        }
       })
       Content(`})
 \`\`\`