@voxgig/sdkgen 1.2.0 → 1.3.1

package/src/helpers/canonType.ts

@@ -0,0 +1,89 @@
+// Canonical type-sentinel -> language primitive type mapper.
+//
+// SOURCE OF TRUTH for the sentinel set: @voxgig/apidef
+//   ~/Projects/voxgig/apidef ts/src/utility.ts  ->  `const VALID_CANON`
+// (around line 908). VALID_CANON maps an OpenAPI type NAME -> a `$SENTINEL`
+// string (e.g. 'string' -> `$STRING`). The model stores those sentinels on
+// every `fields[].type` and op `points[].args.params[].type`.
+//
+// This table maps the SENTINEL the other way -> a concrete primitive type in
+// each target language, so the typed-model generators (EntityTypes_<lang>.ts)
+// can turn the model's field/param sentinels into real language types.
+//
+// Kept as a small duplicate here (rather than importing VALID_CANON) because
+// VALID_CANON is name->sentinel, is not exported from @voxgig/apidef, and would
+// need inverting; a sentinel->type table is what every language generator
+// actually needs. If VALID_CANON gains a new sentinel, add a row below (all
+// languages) and keep the two in sync.
+//
+// KNOWN GAPS (papered over sanely, documented for the port):
+//  - Unknown / missing sentinel  -> the language's "any" (never throws).
+//  - Array element typing is not in the model: $ARRAY maps to an untyped
+//    list/array. `list` ops return T[] via op-kind inference in the op
+//    fragment, NOT via a field sentinel.
+//  - Object/nested field schemas are not in the corpus: $OBJECT maps to the
+//    language's open record/map type.
+//  - No enum/format/nullability beyond the `req` flag.
+
+// Target languages sdkgen supports (go-cli / go-mcp reuse 'go').
+type CanonLang = 'ts' | 'js' | 'py' | 'php' | 'rb' | 'lua' | 'go'
+
+// Bare sentinel key (backticks + leading `$` stripped, upper-cased)
+// -> per-language primitive type name.
+//
+// ONLY the `ts` column is exercised + tested today (the reference target).
+// The other columns are a starting scaffold for the per-language port; verify
+// each against that language's idioms before wiring its EntityTypes_<lang>.ts.
+const CANON_TYPE: Record<string, Record<CanonLang, string>> = {
+  STRING: { ts: 'string', js: 'string', py: 'str', php: 'string', rb: 'String', lua: 'string', go: 'string' },
+  INTEGER: { ts: 'number', js: 'number', py: 'int', php: 'int', rb: 'Integer', lua: 'number', go: 'int' },
+  NUMBER: { ts: 'number', js: 'number', py: 'float', php: 'float', rb: 'Float', lua: 'number', go: 'float64' },
+  BOOLEAN: { ts: 'boolean', js: 'boolean', py: 'bool', php: 'bool', rb: 'Boolean', lua: 'boolean', go: 'bool' },
+  NULL: { ts: 'null', js: 'null', py: 'None', php: 'null', rb: 'NilClass', lua: 'nil', go: 'any' },
+  ARRAY: { ts: 'any[]', js: 'Array', py: 'list', php: 'array', rb: 'Array', lua: 'table', go: '[]any' },
+  OBJECT: { ts: 'Record<string, any>', js: 'Object', py: 'dict', php: 'array', rb: 'Hash', lua: 'table', go: 'map[string]any' },
+  ANY: { ts: 'any', js: '*', py: 'Any', php: 'mixed', rb: 'Object', lua: 'any', go: 'any' },
+}
+
+// Per-language fallback for unknown / missing sentinels.
+// js uses JSDoc's `*` (any type); lua uses `any` (LuaLS).
+const CANON_ANY: Record<CanonLang, string> = {
+  ts: 'any', js: '*', py: 'Any', php: 'mixed', rb: 'Object', lua: 'any', go: 'any',
+}
+
+
+// Normalize a raw sentinel value to its bare upper-case key:
+// '`$STRING`' / '$STRING' / 'string' -> 'STRING'.
+function canonKey(sentinel: unknown): string {
+  if (null == sentinel) {
+    return ''
+  }
+  return String(sentinel).replace(/[`$]/g, '').trim().toUpperCase()
+}
+
+
+// Map a field/param type sentinel to a target-language primitive type.
+// Unknown or missing sentinel -> that language's "any" (never throws).
+function canonToType(sentinel: unknown, lang: string): string {
+  const l = lang as CanonLang
+  const fallback = CANON_ANY[l] ?? 'any'
+
+  const row = CANON_TYPE[canonKey(sentinel)]
+  if (null == row) {
+    return fallback
+  }
+
+  return row[l] ?? fallback
+}
+
+
+export {
+  canonToType,
+  canonKey,
+  CANON_TYPE,
+  CANON_ANY,
+}
+
+export type {
+  CanonLang,
+}

package/src/helpers/collectDeps.ts

@@ -14,17 +14,19 @@
 import { each } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
 
+import type { SdkModel, ModelDep } from '../types'
+
 type DepEntry = {
   name: string
   version: string
   source: 'feature' | 'target'
-  raw: any
+  raw: ModelDep
 }
 
 function collectDeps(
-  model: any,
+  model: SdkModel,
   targetName: string,
-  targetDeps: any,
+  targetDeps: Record<string, ModelDep> | undefined,
 ): DepEntry[] {
   const out: DepEntry[] = []
   const feature = getModelPath(model, `main.${KIT}.feature`)

package/src/helpers/naming.ts

@@ -0,0 +1,59 @@
+// Reserved-word sanitiser for generated doc-example variable names.
+//
+// A doc example binds a variable named after the lowercased entity name
+// (e.g. `const delete = await client.Delete().load()`). When that name is a
+// reserved word in the target language the snippet does not compile
+// (TS1109/TS1389 for `delete`). `safeVarName` appends `_` to any reserved
+// name so the example still reads clearly and compiles.
+//
+// Only languages whose build/vet actually rejects the name are listed. JS and
+// TS share the ECMAScript reserved set (plus the strict-mode / contextual
+// words a `const` binding trips on). Go lists its 25 keywords — a var named
+// `type`/`func`/`range` fails `go build`; Go builtins like `delete`/`len` are
+// NOT keywords and are legal identifiers, so they are intentionally omitted.
+// py/php/rb/lua rarely collide on a lowercased entity name and are not treated
+// here (add a set if a real collision surfaces).
+
+const JS_RESERVED = new Set<string>([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+  'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+  'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new',
+  'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try',
+  'typeof', 'var', 'void', 'while', 'with', 'yield',
+  // strict-mode / contextual words that are invalid as a `const`/`let` binding
+  'await', 'implements', 'interface', 'let', 'package', 'private',
+  'protected', 'public', 'static',
+])
+
+const GO_RESERVED = new Set<string>([
+  'break', 'case', 'chan', 'const', 'continue', 'default', 'defer', 'else',
+  'fallthrough', 'for', 'func', 'go', 'goto', 'if', 'import', 'interface',
+  'map', 'package', 'range', 'return', 'select', 'struct', 'switch', 'type',
+  'var',
+])
+
+const RESERVED: Record<string, Set<string>> = {
+  ts: JS_RESERVED,
+  js: JS_RESERVED,
+  go: GO_RESERVED,
+}
+
+
+// Is `name` a reserved word (an illegal identifier) in the target language?
+function isReservedName(name: string, lang: string): boolean {
+  const set = RESERVED[lang]
+  return !!set && set.has(name)
+}
+
+
+// A collision-free variable name for the target language: the name unchanged
+// unless it is reserved, in which case a trailing `_` is appended.
+function safeVarName(name: string, lang: string): string {
+  return isReservedName(name, lang) ? name + '_' : name
+}
+
+
+export {
+  isReservedName,
+  safeVarName,
+}

package/src/helpers/opExample.ts

@@ -0,0 +1,170 @@
+// Renders a single, type-correct entity-op CALL for the neutral doc
+// components (ReadmeErrors, ReadmeExplanation) that illustrate a convention
+// (throw-on-error, stateful entities) with one representative operation.
+//
+// Two model traps this centralises:
+//   1. OP-AWARENESS — the illustrated op must be one the entity actually
+//      exposes. A create-only entity has no `load` method, so these components
+//      pick the entity's PRIMARY op (entityPrimaryOp) rather than hardcoding
+//      `load`, and this module renders whatever op that is.
+//   2. TYPE-CORRECT MATCH ID — an entity can carry its id ONLY in the
+//      load-match params (no `id` data field). The example id literal is
+//      therefore derived from the OP's param type (opRequestShape), not the
+//      entity fields, so a numeric match id renders `1` and not `"example_id"`
+//      (which would be a TS2322 against a `number` match).
+//
+// Output is the invocation EXPRESSION and its result binding; the surrounding
+// prose / try-catch scaffolding stays in each component's per-language table.
+
+import { each } from 'jostraca'
+import { canonKey } from './canonType'
+import { opRequestShape, entityIdField } from './opShape'
+
+
+type ExampleLang = 'ts' | 'js' | 'py' | 'php' | 'rb' | 'lua' | 'go'
+
+
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+
+// A type-correct literal for a canonical type sentinel, in the target language.
+function litFor(lang: ExampleLang, type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'py' === lang ? 'True' : ('rb' === lang ? 'true' : 'true')
+  if ('ARRAY' === k) return ('lua' === lang) ? '{}' : ('go' === lang ? '[]any{}' : '[]')
+  if ('OBJECT' === k) return ('go' === lang) ? 'map[string]any{}' : '{}'
+  return '"example"'
+}
+
+
+// The example id literal for an op's match key, typed from the op's declared
+// param (falling back to the entity field) so a numeric id is never quoted.
+function idLiteral(ent: any, op: string, idF: string | null): string {
+  if (null == idF) return '"example_id"'
+  const item = opRequestShape(ent, op).items.find((it: any) => it.name === idF)
+  const k = canonKey(item && item.type)
+  return ('INTEGER' === k || 'NUMBER' === k) ? '1' : '"example_id"'
+}
+
+
+// Render a match object `{ idF: idLit }` (or empty when the entity has no id
+// key) in the target language's object syntax.
+function matchArg(lang: ExampleLang, idF: string | null, idLit: string): string {
+  if (null == idF) return 'go' === lang ? 'nil' : ''
+  switch (lang) {
+    case 'py': return `{"${idF}": ${idLit}}`
+    case 'php': return `["${idF}" => ${idLit}]`
+    case 'rb': return `{ "${idF}" => ${idLit} }`
+    case 'lua': return `{ ${idF} = ${idLit} }`
+    case 'go': return `map[string]any{"${idF}": ${idLit}}`
+    default: return `{ ${idF}: ${idLit} }`
+  }
+}
+
+
+// The entity's required writable fields for a create/update body, rendered as
+// `key: value` pairs (capped) in the target language's object syntax. Ensures
+// the body satisfies a typed CreateData/UpdateData (required fields present).
+function dataArg(lang: ExampleLang, ent: any, op: string, idF: string | null): string {
+  const items = opRequestShape(ent, op).items
+    .filter((it: any) => it.name !== idF && it.name !== 'id')
+  const required = items.filter((it: any) => !it.optional)
+  // ALL required fields must appear (a typed CreateData rejects a partial); cap
+  // only the optional fallback used when the op declares no required field.
+  const chosen = required.length ? required : items.slice(0, 3)
+  const pairs = chosen.map((it: any) => {
+    const v = litFor(lang, it.type)
+    switch (lang) {
+      case 'py': return `"${it.name}": ${v}`
+      case 'php': return `"${it.name}" => ${v}`
+      case 'rb': return `"${it.name}" => ${v}`
+      case 'lua': return `${it.name} = ${v}`
+      case 'go': return `"${it.name}": ${v}`
+      default: return `${it.name}: ${v}`
+    }
+  })
+  switch (lang) {
+    case 'php': return `[${pairs.join(', ')}]`
+    case 'lua': return `{ ${pairs.join(', ')} }`
+    case 'go': return `map[string]any{${pairs.join(', ')}}`
+    default: return `{ ${pairs.join(', ')} }`
+  }
+}
+
+
+type PrimaryCall = {
+  // The full invocation expression, e.g. `client.Advice().load({ id: 1 })`
+  // (ts) or `client.Generate(nil).Create(map[string]any{...}, nil)` (go).
+  expr: string
+  // The natural result-variable name (`advice`, `advices`, `generate`).
+  resultVar: string
+  // True when the op returns no value (remove) — callers that print the
+  // result should skip it.
+  isVoid: boolean
+}
+
+
+// Render the entity's PRIMARY-op invocation in `lang`. `eName` is the
+// Capitalised entity name, `eLower` the variable-safe lowercase name, `op` the
+// primary op name. Method spelling / factory syntax follow each language's
+// idiom (Go PascalCase + ctrl arg, Lua `:` calls, Ruby paren-less factory).
+function primaryOpCall(
+  lang: ExampleLang,
+  eName: string,
+  eLower: string,
+  op: string,
+  idF: string | null,
+  ent: any,
+): PrimaryCall {
+  const isMatch = 'load' === op || 'remove' === op
+  const isList = 'list' === op
+  const isData = 'create' === op || 'update' === op
+  const idLit = idLiteral(ent, op, idF)
+
+  // Factory + method spelling per language.
+  const method = 'go' === lang ? cap(op) : op
+  let factory: string
+  let sep: string
+  if ('go' === lang) { factory = `client.${eName}(nil)`; sep = '.' }
+  else if ('lua' === lang) { factory = `client:${eName}()`; sep = ':' }
+  else if ('rb' === lang) { factory = `client.${eName}`; sep = '.' }
+  else if ('php' === lang) { factory = `$client->${eName}()`; sep = '->' }
+  else { factory = `client.${eName}()`; sep = '.' }
+
+  // Argument string per op + language.
+  let arg: string
+  if (isList) {
+    arg = 'go' === lang ? 'nil' : ''
+  } else if (isMatch) {
+    arg = matchArg(lang, idF, idLit)
+  } else if (isData) {
+    arg = dataArg(lang, ent, op, idF)
+  } else {
+    arg = 'go' === lang ? 'nil' : ''
+  }
+  // Go passes a trailing ctrl arg on every entity method.
+  if ('go' === lang) {
+    arg = arg + ', nil'
+  }
+
+  const expr = `${factory}${sep}${method}(${arg})`
+  const resultVar = isList ? eLower + 's' : eLower
+  return { expr, resultVar, isVoid: 'remove' === op }
+}
+
+
+export {
+  primaryOpCall,
+  idLiteral,
+  matchArg,
+  dataArg,
+  litFor,
+}
+
+export type {
+  ExampleLang,
+  PrimaryCall,
+}

package/src/helpers/opShape.ts

@@ -0,0 +1,236 @@
+// Per-op request-payload shape + partiality policy for the typed-model
+// generators (EntityTypes_<lang>.ts).
+//
+// SINGLE SOURCE OF TRUTH for two things every language generator needs:
+//   1. The type-name scheme: <Name>{Load,List,Remove}Match /
+//      <Name>{Create,Update}Data (OP_SUFFIX + opTypeName).
+//   2. Which fields make up an op's request payload, and whether each is
+//      required or optional (opRequestShape) — i.e. the partiality policy.
+//
+// PARTIALITY POLICY
+//   Op-declared params win: if the op declares params
+//   (op.<name>.points[].args.params[]), the payload is built from them and a
+//   param is optional iff `reqd === false` (this is how path/query params such
+//   as {id} become required). `fromParams` is true in that case.
+//
+//   Otherwise the payload mirrors the entity's fields, filtered to those active
+//   for the op (field.op[opname].active !== false; absent -> participates), and
+//   optionality is decided per-op:
+//     create -> required iff `field.req` (server-shaped required fields);
+//     update -> all optional (patch);
+//     load / remove -> a field named `id` is required, the rest optional
+//       (best-effort key convention; degrades to all-optional if no `id`);
+//     list -> all optional (filter).
+//
+// The generators consume `items` (each already carrying its final `optional`
+// flag) and render them in the target language's struct/interface/TypedDict
+// syntax; the policy itself is language-neutral and tested in isolation.
+
+import { each } from 'jostraca'
+
+
+// The five ops, and whether their request payload is a `Match` (query/id) or
+// `Data` (body) — this fixes the generated type-name suffix per op.
+const OP_SUFFIX: Record<string, 'Match' | 'Data'> = {
+  load: 'Match',
+  list: 'Match',
+  remove: 'Match',
+  create: 'Data',
+  update: 'Data',
+}
+
+
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+
+// The generated type name for an op's request payload, e.g. AdviceLoadMatch.
+function opTypeName(Name: string, opname: string): string {
+  return Name + cap(opname) + (OP_SUFFIX[opname] || 'Match')
+}
+
+
+// One request-payload member: a model field or op param, with the final
+// required/optional decision already applied per the partiality policy.
+type OpShapeItem = {
+  name: string
+  type: any     // canonical type sentinel (e.g. `$STRING`); render via canonToType
+  optional: boolean
+}
+
+
+// Collect an op's params, deduped by name across all of its points.
+function opParams(op: any): any[] {
+  const points = op && op.points ? each(op.points) : []
+  const seen: Record<string, boolean> = {}
+  const out: any[] = []
+  points.forEach((pt: any) => {
+    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    params.forEach((p: any) => {
+      if (p && null != p.name && !seen[p.name]) {
+        seen[p.name] = true
+        out.push(p)
+      }
+    })
+  })
+  return out
+}
+
+
+// Does a field participate in an op? Absent op-entry -> participates; only an
+// explicit `active: false` excludes it.
+function fieldInOp(field: any, opname: string): boolean {
+  const fop = field && field.op && field.op[opname]
+  return null == fop || fop.active !== false
+}
+
+
+// Decide optionality for a field in a no-params request payload, per op.
+function fieldOptional(field: any, opname: string): boolean {
+  switch (opname) {
+    case 'create':
+      // Respect the model's required flag: required unless req === false.
+      return false === field.req
+    case 'update':
+      // Patch semantics — every field optional.
+      return true
+    case 'load':
+    case 'remove':
+      // Best-effort key convention: the `id` field is required, rest optional.
+      return 'id' !== field.name
+    case 'list':
+    default:
+      // Filter — every field optional.
+      return true
+  }
+}
+
+
+// The ordered request-payload members for an entity op, with each member's
+// required/optional decision baked in. `fromParams` records whether the op's
+// declared params were used (true) or the entity-field fallback (false).
+function opRequestShape(ent: any, opname: string):
+  { items: OpShapeItem[], fromParams: boolean } {
+
+  const op = ent && ent.op ? ent.op[opname] : null
+  if (null == op) {
+    return { items: [], fromParams: false }
+  }
+
+  const params = opParams(op)
+  if (0 < params.length) {
+    const items = params.map((p: any) => ({
+      name: p.name,
+      type: p.type,
+      optional: false === p.reqd,
+    }))
+    return { items, fromParams: true }
+  }
+
+  const fields = (ent.fields ? each(ent.fields) : [])
+    .filter((f: any) => f.active !== false)
+    .filter((f: any) => fieldInOp(f, opname))
+
+  const items = fields.map((f: any) => ({
+    name: f.name,
+    type: f.type,
+    optional: fieldOptional(f, opname),
+  }))
+
+  return { items, fromParams: false }
+}
+
+
+// The entity's id-like key field, or null when it has none. Used by the doc
+// generators to decide whether an example may key a load/remove on `{ id: ... }`
+// and access `.id` on a returned entity, OR must degrade to `load()` with no
+// argument (some APIs model an entity whose load match carries no id — e.g. a
+// response-wrapped spec, where AqiLoadMatch is { code, data, msg }). Prefers the
+// model's declared id field name, then a literal `id`, checking the load-match
+// shape first and the entity's own fields as a fallback.
+function entityIdField(ent: any): string | null {
+  if (null == ent) {
+    return null
+  }
+  const idName = (ent.id && ent.id.field) || 'id'
+  const loadItems = opRequestShape(ent, 'load').items
+  if (loadItems.some((it: OpShapeItem) => it.name === idName)) {
+    return idName
+  }
+  if (loadItems.some((it: OpShapeItem) => it.name === 'id')) {
+    return 'id'
+  }
+  // NO fallback to entity.fields: this is the load-MATCH key. An entity whose
+  // DATA type has an `id` field but whose load match does NOT (a query-param
+  // load, e.g. playstation-store's StoreLoadMatch { age, country, ... }) must
+  // degrade to a no-arg load(); `.id` access is decided by entityDataIdField.
+  return null
+}
+
+
+// The entity's ACTIVE op names, in canonical CRUD order (list, load, create,
+// update, remove), with any non-canonical ops appended in sorted order. Doc
+// generators must gate an op example on this (an op present in the model but
+// `active: false` generates no method, so an example calling it would not
+// compile) — NOT on the raw `Object.keys(ent.op)`, which includes inactive ops.
+const CANON_OP_ORDER = ['list', 'load', 'create', 'update', 'remove']
+
+function entityOps(ent: any): string[] {
+  const ops = (ent && ent.op) || {}
+  const active = Object.keys(ops).filter((o: string) => ops[o] && ops[o].active !== false)
+  return CANON_OP_ORDER.filter((o) => active.includes(o))
+    .concat(active.filter((o) => !CANON_OP_ORDER.includes(o)).sort())
+}
+
+
+// The entity's primary/representative op for a single illustrative call —
+// prefer a read op (list, then load) so the snippet needs no fabricated match,
+// then fall back to create/update/remove. null when the entity exposes no op.
+// Doc generators MUST pick their "primary" op through this rather than
+// hardcoding `load`: a create-only entity has no `load` method.
+function entityPrimaryOp(ent: any): string | null {
+  const ops = entityOps(ent)
+  for (const o of CANON_OP_ORDER) {
+    if (ops.includes(o)) {
+      return o
+    }
+  }
+  return ops[0] || null
+}
+
+
+// The id field on the entity's DATA type (its fields[]), or null. DISTINCT from
+// entityIdField (the load-MATCH key): an API can model a load match that carries
+// an `id` param while the response entity itself has no `id` field, so `.id`
+// access on a RETURNED record must be guarded on this, not on the match key.
+function entityDataIdField(ent: any): string | null {
+  if (null == ent) {
+    return null
+  }
+  const idName = (ent.id && ent.id.field) || 'id'
+  const fields = ent.fields ? each(ent.fields) : []
+  if (fields.some((f: any) => f && f.name === idName)) {
+    return idName
+  }
+  if (fields.some((f: any) => f && f.name === 'id')) {
+    return 'id'
+  }
+  return null
+}
+
+
+export {
+  OP_SUFFIX,
+  opTypeName,
+  opParams,
+  opRequestShape,
+  entityIdField,
+  entityDataIdField,
+  entityOps,
+  entityPrimaryOp,
+}
+
+export type {
+  OpShapeItem,
+}