@voxgig/sdkgen 1.3.14 → 1.3.18

package/src/helpers/naming.ts

@@ -69,6 +69,63 @@ const RESERVED: Record<string, Set<string>> = {
 }
 
 
+// Ruby CORE CONSTANTS — a different hazard from the keyword sets above.
+//
+// The keyword sets guard local-variable BINDINGS. This set guards generated
+// top-level CONSTANTS. Ruby constants share one namespace with the core
+// classes, and reassigning one is not an error — it silently replaces it:
+//
+//   File = Struct.new(:name)     # ::File is now a Struct
+//   File.join('a', 'b')          # NoMethodError — every later caller breaks
+//
+// The typed model emits `<Name> = Struct.new(...)` per entity, so an API with
+// a `/files` collection (entity `File`) used to clobber Ruby's File class and
+// take the whole SDK down with it — the generated test runner calls
+// `File.join` to locate `.env.local`, so `rb` failed at require time.
+//
+// Only names Ruby itself defines at top level are listed: reassigning any of
+// them breaks working code somewhere. Names that merely LOOK builtin but are
+// not core constants (e.g. `Response`, `Record`) are safe and stay untouched,
+// which keeps the rename off every SDK that does not actually collide.
+const RB_CORE_CONSTANTS = new Set<string>([
+  // classes an entity name plausibly lands on
+  'Array', 'Binding', 'Class', 'Comparable', 'Complex', 'Data', 'Dir',
+  'Encoding', 'Enumerator', 'Exception', 'Fiber', 'File', 'Float', 'Hash',
+  'IO', 'Integer', 'Method', 'Module', 'Mutex', 'Numeric', 'Object', 'Proc',
+  'Queue', 'Random', 'Range', 'Rational', 'Regexp', 'Set', 'Signal', 'String',
+  'Struct', 'Symbol', 'Thread', 'Time', 'UnboundMethod',
+  // modules / singletons
+  'Enumerable', 'GC', 'Kernel', 'Marshal', 'Math', 'ObjectSpace', 'Process',
+  'Warning',
+  // the rest of the exception hierarchy an API might name an entity after
+  'ArgumentError', 'IndexError', 'IOError', 'KeyError', 'NameError',
+  'NotImplementedError', 'RangeError', 'RuntimeError', 'StandardError',
+  'StopIteration', 'SystemExit', 'TypeError', 'ZeroDivisionError',
+  // literal singletons
+  'FalseClass', 'NilClass', 'TrueClass',
+])
+
+
+// Is `Name` a constant Ruby already defines at top level?
+function isRbCoreConstant(Name: string): boolean {
+  return RB_CORE_CONSTANTS.has(Name)
+}
+
+
+// A top-level-safe Ruby constant name for a generated type: the name
+// unchanged, unless Ruby core already owns it, in which case `Type` is
+// appended (`File` -> `FileType`). Applied ONLY to the bare entity data type
+// — the per-op type names always carry a suffix (`FileCreateData`,
+// `FileLoadMatch`), which no core constant matches.
+//
+// The entity ACCESSOR keeps its original name (`client.File(...)`): methods
+// and constants live in separate namespaces in Ruby, so the accessor never
+// collided and the public surface is unchanged.
+function rbSafeTypeName(Name: string): string {
+  return isRbCoreConstant(Name) ? Name + 'Type' : Name
+}
+
+
 // Is `name` a reserved word (an illegal identifier) in the target language?
 function isReservedName(name: string, lang: string): boolean {
   const set = RESERVED[lang]
@@ -83,7 +140,56 @@ function safeVarName(name: string, lang: string): string {
 }
 
 
+// A variable name for a doc EXAMPLE entity. Doc examples bind the SDK instance
+// to `client` (e.g. `const client = ...SDK.test()`), so an entity whose
+// lowercased name is also `client` — an API with a `Client` entity — would
+// shadow it: `const client = client.Client()...` is self-referential (TS2448/
+// TS7022) and breaks the readme_examples type-check. Append `_` to keep the
+// example variable distinct from the SDK instance. Also applies the normal
+// language-reserved-word guard.
+function exampleVarName(name: string, lang: string): string {
+  const v = safeVarName(name, lang)
+  return 'client' === v ? v + '_' : v
+}
+
+
+// A valid ECMAScript identifier — the only shape `obj.name` can express.
+const JS_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+
+// A safe JS/TS property-access expression for a SPEC-DERIVED key: dot
+// notation when the key is a valid identifier, bracket notation otherwise.
+// OpenAPI path/query parameter names are not constrained to identifiers —
+// e.g. Evervault's `/payments/3ds-sessions/{3ds_session_id}` yields
+// `3ds_session_id`, and `params.3ds_session_id` is a syntax error (TS1434).
+// The other language targets already quote these keys (`params["..."]`);
+// this keeps ts/js in parity.
+function jsProp(obj: string, name: string): string {
+  return JS_IDENT.test(name) ? `${obj}.${name}` : `${obj}[${JSON.stringify(name)}]`
+}
+
+
+// A safe JS/TS OBJECT-LITERAL key for a spec-derived field name: bare when
+// the name is a valid identifier, single-quoted otherwise. `{ 3ds_session_id:
+// 1 }` is a syntax error (TS1351) — doc examples must quote such keys.
+function jsKey(name: string): string {
+  return JS_IDENT.test(name) ? name : `'${name}'`
+}
+
+
+// As `jsProp`, but optional-chained: `obj?.name` / `obj?.["3ds_session_id"]`.
+function jsOptProp(obj: string, name: string): string {
+  return JS_IDENT.test(name) ? `${obj}?.${name}` : `${obj}?.[${JSON.stringify(name)}]`
+}
+
+
 export {
   isReservedName,
   safeVarName,
+  exampleVarName,
+  isRbCoreConstant,
+  rbSafeTypeName,
+  jsProp,
+  jsOptProp,
+  jsKey,
 }

package/src/helpers/opExample.ts

@@ -52,15 +52,48 @@ function idLiteral(ent: any, op: string, idF: string | null): string {
 
 // 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' : ''
+// Spec-derived field names are NOT constrained to be identifiers — e.g.
+// Evervault's `/payments/3ds-sessions/{3ds_session_id}` yields the match key
+// `3ds_session_id`. py/php/rb/go quote every literal key already, but ts/js
+// (`{ key: v }`) and lua (`{ key = v }`) write them bare, and a leading digit
+// or a `-` makes that a syntax error (TS1351 / Lua "'}' expected"). Quote
+// exactly those, leaving ordinary keys in the idiomatic bare form.
+const JS_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+const LUA_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+// A `key<sep>value` literal pair in the target language's object syntax.
+function litPair(lang: ExampleLang, name: string, value: string): string {
   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} }`
+    case 'py': return `"${name}": ${value}`
+    case 'php': return `"${name}" => ${value}`
+    case 'rb': return `"${name}" => ${value}`
+    case 'go': return `"${name}": ${value}`
+    case 'lua': return LUA_IDENT.test(name) ?
+      `${name} = ${value}` : `["${name}"] = ${value}`
+    default: return JS_IDENT.test(name) ?
+      `${name}: ${value}` : `'${name}': ${value}`
+  }
+}
+
+
+// The match argument for a load/remove — ALL required match params, not just
+// the primary id. A composite-match entity (e.g. Umbrella's FlatPermission,
+// `/public/database/{id}/permission/{msisdn}`) has two required path params
+// (database_id + id); emitting only `{ id }` fails the typed <Name>LoadMatch.
+// The idF field takes the specific id literal; other required fields take a
+// type-correct example value (mirrors dataArg).
+function matchArg(
+  lang: ExampleLang, ent: any, op: string, idF: string | null, idLit: string
+): string {
+  const items = opRequestShape(ent, op).items.filter((it: any) => !it.optional)
+  if (0 === items.length) return 'go' === lang ? 'nil' : ''
+  const pairs = items.map((it: any) =>
+    litPair(lang, it.name, it.name === idF ? idLit : litFor(lang, it.type)))
+  switch (lang) {
+    case 'py': return `{${pairs.join(', ')}}`
+    case 'php': return `[${pairs.join(', ')}]`
+    case 'go': return `map[string]any{${pairs.join(', ')}}`
+    default: return `{ ${pairs.join(', ')} }`
   }
 }
 
@@ -75,17 +108,7 @@ function dataArg(lang: ExampleLang, ent: any, op: string, idF: string | null): s
   // 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}`
-    }
-  })
+  const pairs = chosen.map((it: any) => litPair(lang, it.name, litFor(lang, it.type)))
   switch (lang) {
     case 'php': return `[${pairs.join(', ')}]`
     case 'lua': return `{ ${pairs.join(', ')} }`
@@ -139,7 +162,7 @@ function primaryOpCall(
   if (isList) {
     arg = 'go' === lang ? 'nil' : ''
   } else if (isMatch) {
-    arg = matchArg(lang, idF, idLit)
+    arg = matchArg(lang, ent, op, idF, idLit)
   } else if (isData) {
     arg = dataArg(lang, ent, op, idF)
   } else {

package/src/helpers/opShape.ts

@@ -26,7 +26,60 @@
 // 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'
+import { each, names } from 'jostraca'
+import { KIT, getModelPath } from '@voxgig/apidef'
+
+
+// THE entity collection for a model — resolved once, with a stable identity.
+//
+// Two problems this solves, both caused by every component calling
+// `getModelPath(model, 'main.<KIT>.entity')` for itself:
+//
+//   * CORRECTNESS. getModelPath drops `active: false` entries by default, but
+//     the consumer scaffold (create-sdkgen Root.ts) generates entity code for
+//     EVERY entity and every EntityTypes_<lang> emits data types with
+//     `only_active: false`. Class-name assignment done against the filtered
+//     view cannot see the inactive entities whose data types it must avoid.
+//     This resolver always returns the unfiltered collection.
+//
+//   * PERFORMANCE. getModelPath REBUILDS the container object on every call
+//     when filtering, so the WeakMap memos below never hit across callers —
+//     the O(n·ops) class-name assignment re-ran per entity per target. At 500
+//     entities x 22 targets that was ~15s of pure recomputation; caching the
+//     resolved collection on the model makes it ~3ms.
+const _entityCollCache = new WeakMap<object, any>()
+
+function entityCollection(model: any): any {
+  if (null == model || 'object' !== typeof model) {
+    return {}
+  }
+  const cached = _entityCollCache.get(model)
+  if (null != cached) {
+    return cached
+  }
+  const coll = getModelPath(model, `main.${KIT}.entity`,
+    { only_active: false, required: false }) || {}
+  deriveEntityNames(coll)
+  _entityCollCache.set(model, coll)
+  return coll
+}
+
+
+// Derive the PascalCase `Name` on every entity in a collection.
+//
+// `Name` is injected LAZILY by jostraca's names(), historically by whichever
+// component happened to run first (create-sdkgen Root.ts, or an EntityTypes
+// emitter). Anything reading `e.Name` before that ran saw `undefined` — and
+// because the helpers below MEMOISE, one early read poisoned the result for
+// the whole run (`undefinedEntity` class names; a permanently empty collision
+// list). The helpers therefore derive `Name` themselves, up front, so they
+// never depend on component ordering. Idempotent: names() is only called for
+// an entity that lacks `Name`.
+function deriveEntityNames(entityColl: any): any[] {
+  const ents = each(entityColl).filter((e: any) => e && null != e.name)
+  ents.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
+  return ents
+}
 
 
 // The five ops, and whether their request payload is a `Match` (query/id) or
@@ -156,8 +209,21 @@ function opRequestShape(ent: any, opname: string):
     return { items: [], fromParams: false }
   }
 
+  // Ops that carry a BODY are the exception to "op-declared params win":
+  // their request payload is BOTH. `PUT /v1/todo/item/{id}` declares the path
+  // param `id`, which the SDK resolves out of reqdata (see the param
+  // utility's reqmatch -> match -> reqdata search), while the fields the
+  // caller wants to change come from the entity. Params alone produced
+  // `<Name>UpdateData = { id }` — no way to send anything to update.
+  //
+  // The param stays in the payload because the path needs it; keeping it out
+  // of the request BODY is the model's job, via the op's `transform.req`
+  // (@voxgig/apidef restricts the body to a closed request schema's declared
+  // properties).
+  const isbodyop = 'create' === opname || 'update' === opname || 'patch' === opname
+
   const params = opParams(op)
-  if (0 < params.length) {
+  if (0 < params.length && !isbodyop) {
     const items = params.map((p: any) => ({
       name: p.name,
       type: p.type,
@@ -166,15 +232,25 @@ function opRequestShape(ent: any, opname: string):
     return { items, fromParams: true }
   }
 
+  const paramItems = isbodyop ? params.map((p: any) => ({
+    name: p.name,
+    type: p.type,
+    optional: false === p.reqd,
+  })) : []
+  const paramNames = new Set(paramItems.map((p: any) => p.name))
+
   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),
-  }))
+  const items = paramItems.concat(
+    fields
+      .filter((f: any) => !paramNames.has(f.name))
+      .map((f: any) => ({
+        name: f.name,
+        type: f.type,
+        optional: fieldOptional(f, opname),
+      })))
 
   return { items, fromParams: false }
 }
@@ -250,6 +326,16 @@ function entityPrimaryOp(ent: any): string | null {
 // … The DATA type keeps its canonical `<Name>` — only the suffixed class
 // yields. Deterministic (sorted-key iteration) and stable across runs.
 //
+// Covers EVERY entity, active or not: the consumer scaffold (create-sdkgen
+// Root.ts) iterates the RAW entity collection, and every EntityTypes_<lang>
+// emits with `only_active: false`, so an inactive entity still contributes a
+// generated data type AND still needs a class name. Filtering to actives here
+// left inactive entities on the un-deduped `<Name>Entity` fallback and left
+// their data types out of `taken` — so an ACTIVE entity's class could collide
+// with an INACTIVE entity's emitted data type (e.g. active `project` ->
+// class `ProjectEntity` vs inactive `project-entity` -> type `ProjectEntity`,
+// a redeclaration in Go).
+//
 // Memoised per entity-collection object so the O(n) assignment runs once.
 const _classNameCache = new WeakMap<object, Record<string, string>>()
 
@@ -259,7 +345,7 @@ function entityClassNames(entityColl: any): Record<string, string> {
     return cached
   }
 
-  const ents = each(entityColl).filter((e: any) => e && e.active !== false)
+  const ents = deriveEntityNames(entityColl)
 
   // 1. Every top-level DATA-type name the target emits.
   const taken: Record<string, boolean> = {}
@@ -305,6 +391,63 @@ function entityClassName(ent: any, entityColl: any): string {
 }
 
 
+// Cross-entity TYPE-name collision detection. entityClassNames keeps CLASS
+// names collision-free, but the DATA/op type names are the raw `<Name>` /
+// opTypeName(...) — two entities whose PascalCase Name coincides (e.g.
+// `foo-bar` vs `foo_bar`), or a data-type name equal to another entity's
+// op-type name, emit DUPLICATE top-level type declarations: a redeclaration
+// compile error in go/rust/c/cpp/csharp and the JVM containers, silent
+// merging in ts. The names cannot be auto-renamed here — the generated
+// entity classes and op fragments reference them by token — so the guard
+// surfaces the collision loudly instead. Returns the sorted duplicate names
+// (empty when clean). `Name` is derived here (deriveEntityNames), so the
+// guard cannot be silently disabled by running before an emitter.
+//
+// Memoised per entity-collection object, like entityClassNames.
+const _typeCollisionCache = new WeakMap<object, string[]>()
+
+function entityTypeCollisions(entityColl: any): string[] {
+  const cached = _typeCollisionCache.get(entityColl)
+  if (null != cached) {
+    return cached
+  }
+
+  const counts: Record<string, number> = {}
+  const bump = (n: string) => { counts[n] = (counts[n] || 0) + 1 }
+
+  deriveEntityNames(entityColl)
+    .forEach((e: any) => {
+      bump(e.Name)
+      for (const op of ['load', 'list', 'create', 'update', 'remove']) {
+        if (e.op && e.op[op]) {
+          bump(opTypeName(e.Name, op))
+        }
+      }
+    })
+
+  const out = Object.keys(counts).filter((n) => 1 < counts[n]).sort()
+  _typeCollisionCache.set(entityColl, out)
+  return out
+}
+
+
+// Emitter convenience: warn (once per collection per target run) when the
+// generated typed model would contain duplicate top-level type names.
+function warnEntityTypeCollisions(entityColl: any, log: any, lang: string): string[] {
+  const dups = entityTypeCollisions(entityColl)
+  if (0 < dups.length && log && log.warn) {
+    log.warn({
+      point: 'entity-types-name-collision', lang, names: dups,
+      note: `${lang}: duplicate generated type name(s) ${dups.join(', ')} — ` +
+        `two entities produce the same PascalCase type name; rename one ` +
+        `entity (or alias it) in the model or the generated typed model ` +
+        `will not compile in statically-typed targets`,
+    })
+  }
+  return dups
+}
+
+
 // Pick a representative entity for a single illustrative snippet (e.g. the
 // README's test-mode example): the first ACTIVE entity that exposes a read
 // op (list/load) so the snippet is meaningful, else the first with ANY
@@ -315,16 +458,55 @@ function entityClassName(ent: any, entityColl: any): string {
 // for deterministic output.
 function pickExampleEntity(entity: any): { entity: any, primaryOp: string | null } {
   const actives = each(entity).filter((e: any) => e && e.active !== false)
-  const readable = actives.find((e: any) => {
+  const readable = actives.filter((e: any) => {
     const op = entityPrimaryOp(e)
     return 'list' === op || 'load' === op
   })
-  const withOp = actives.find((e: any) => null != entityPrimaryOp(e))
-  const chosen = readable || withOp || actives[0] || null
+  const withOp = actives.filter((e: any) => null != entityPrimaryOp(e))
+  // Prefer a readable entity, then any entity with an op, then anything at all.
+  // WITHIN the chosen tier pick an entity of MEDIAN "size" — median name length
+  // and median field count — so the generated README/examples showcase a
+  // representative entity, not the alphabetically-first one (often a degenerate
+  // stub with a terse name and no fields) nor an atypically sprawling one.
+  const pool = readable.length ? readable : (withOp.length ? withOp : actives)
+  const chosen = pickMedianEntity(pool)
   return { entity: chosen, primaryOp: null == chosen ? null : entityPrimaryOp(chosen) }
 }
 
 
+// The pool entity closest to the median on both axes (name length, field
+// count). Distance on each axis is normalised by that axis's own median so the
+// two are comparable, then summed. Ties keep the pool's existing key-sorted
+// order (each() is byte-stable), so the pick is deterministic.
+function pickMedianEntity(pool: any[]): any {
+  if (0 === pool.length) return null
+  if (1 === pool.length) return pool[0]
+  const fieldCount = (e: any): number => (e && e.fields ? each(e.fields).length : 0)
+  const nameLen = (e: any): number => (e && e.name ? String(e.name).length : 0)
+  const medName = medianOf(pool.map(nameLen))
+  const medField = medianOf(pool.map(fieldCount))
+  let best = pool[0]
+  let bestScore = Infinity
+  for (const e of pool) {
+    const score =
+      Math.abs(nameLen(e) - medName) / (medName || 1) +
+      Math.abs(fieldCount(e) - medField) / (medField || 1)
+    if (score < bestScore) {
+      bestScore = score
+      best = e
+    }
+  }
+  return best
+}
+
+
+function medianOf(xs: number[]): number {
+  const s = xs.slice().sort((a, b) => a - b)
+  const m = Math.floor(s.length / 2)
+  return 0 === s.length ? 0 : (s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2)
+}
+
+
 // 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`
@@ -347,6 +529,8 @@ function entityDataIdField(ent: any): string | null {
 
 export {
   OP_SUFFIX,
+  deriveEntityNames,
+  entityCollection,
   opTypeName,
   opParams,
   opRequestShape,
@@ -356,6 +540,8 @@ export {
   entityPrimaryOp,
   pickExampleEntity,
   entityClassName,
+  entityTypeCollisions,
+  warnEntityTypeCollisions,
 }
 
 export type {

package/src/sdkgen.ts

@@ -5,7 +5,7 @@ import Path from 'node:path'
 
 import { prettyPino, Pino } from '@voxgig/util'
 
-import { Jsonic } from 'jsonic'
+import { Jsonic } from '@tabnas/jsonic'
 import * as JostracaModule from 'jostraca'
 import { Aontu } from 'aontu'
 
@@ -51,8 +51,8 @@ import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
 import { canonToType, canonKey } from './helpers/canonType'
-import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName } from './helpers/opShape'
-import { isReservedName, safeVarName } from './helpers/naming'
+import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
+import { isReservedName, safeVarName, exampleVarName, isRbCoreConstant, rbSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
 import {
   packageName,
   installCommand,
@@ -471,8 +471,18 @@ export {
   entityPrimaryOp,
   pickExampleEntity,
   entityClassName,
+  entityTypeCollisions,
+  warnEntityTypeCollisions,
+  deriveEntityNames,
+  entityCollection,
   isReservedName,
   safeVarName,
+  exampleVarName,
+  isRbCoreConstant,
+  rbSafeTypeName,
+  jsProp,
+  jsOptProp,
+  jsKey,
 
   packageName,
   installCommand,

package/src/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "esModuleInterop": true,
+    "composite": true,
     "module": "nodenext",
     "noEmitOnError": true,
     "skipLibCheck": true,
@@ -10,6 +11,7 @@
     "sourceMap": true,
     "strict": true,
     "target": "es2021",
+    "types": ["node"],
     "declaration": true,
     "declarationDir": "../dist"
   }

package/project/.sdk/tm/zig/build.zig.zon

@@ -1,11 +0,0 @@
-.{
-    .name = "voxgig_sdk",
-    .version = "0.0.1",
-    .dependencies = .{},
-    .paths = .{
-        "src",
-        "test",
-        "build.zig",
-        "build.zig.zon",
-    },
-}