@voxgig/sdkgen 1.3.4 → 1.3.6

package/src/cmp/ReadmeErrors.ts

@@ -6,7 +6,7 @@ import {
   getModelPath
 } from '../types'
 
-import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { entityIdField, pickExampleEntity } from '../helpers/opShape'
 import { primaryOpCall } from '../helpers/opExample'
 import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
 import { safeVarName } from '../helpers/naming'
@@ -224,29 +224,28 @@ const ReadmeErrors = cmp(function ReadmeErrors(props: any) {
 
   const lang = LANGS[target.name] || DEFAULT_LANG
 
-  // Derive a real example entity from the model (the same way the sibling
-  // Readme components do) so the snippet never references a phantom entity.
+  // Pick a real example entity WITH a real op (prefer a read op) so the
+  // error-handling snippet never references a phantom entity or fabricates a
+  // `.load()` on an op-less one (e.g. Cloudsmith's `Abort`). primaryOp is null
+  // only when NO entity exposes any op — then the entity example is skipped
+  // and only the direct() error handling (which every SDK has) is shown.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
-  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
-  // Sanitise the variable name against the target's reserved words (a `Delete`
-  // entity must not bind `const delete = ...`).
-  const eLower = safeVarName(eName.toLowerCase(), target.name)
-
-  // The entity's id-like key field name, or null when it has none.
-  const idF = entityIdField(ex)
-  // The entity's PRIMARY op — an op it actually exposes (prefer list/load, else
-  // create/update/remove). A create-only entity therefore never shows a
-  // phantom `.load()`.
-  const primaryOp = entityPrimaryOp(ex) || 'load'
-  const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+  const { entity: ex, primaryOp } = pickExampleEntity(entity || {})
 
   Content(`
 ## Error handling
 
 `)
 
-  Content(lang.entity(call, primaryOp))
+  if (ex && primaryOp) {
+    const eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
+    // Sanitise the variable name against the target's reserved words (a
+    // `Delete` entity must not bind `const delete = ...`).
+    const eLower = safeVarName(eName.toLowerCase(), target.name)
+    const idF = entityIdField(ex)
+    const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+    Content(lang.entity(call, primaryOp))
+  }
 
   Content(lang.direct)
 })

package/src/cmp/ReadmeExplanation.ts

@@ -8,7 +8,7 @@ import {
 
 import { requirePath } from '../utility'
 
-import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { entityIdField, pickExampleEntity } from '../helpers/opShape'
 import { idLiteral, matchArg, dataArg } from '../helpers/opExample'
 import type { ExampleLang } from '../helpers/opExample'
 import { safeVarName } from '../helpers/naming'
@@ -225,39 +225,40 @@ const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
   const feature = getModelPath(model, `main.${KIT}.feature`)
   const lang = LANGS[target.name] || DEFAULT_LANG
 
-  // Derive a real example entity from the model (the same way the sibling
-  // Readme components do) so the entity-state example never references a
-  // phantom entity.
+  // Pick a real example entity WITH a real op (prefer a read op) so the
+  // entity-state example never references a phantom entity or fabricates a
+  // `.load()` on an op-less one (e.g. Cloudsmith's `Abort`). primaryOp is null
+  // only when NO entity exposes any op — then the entity-state section is
+  // skipped (a direct()-only SDK has no entity op to illustrate).
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
-  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
-  // Sanitise against the target's reserved words (a `Delete` entity must not
-  // bind `const delete = ...`).
-  const eLower = safeVarName(eName.toLowerCase(), target.name)
+  const { entity: ex, primaryOp } = pickExampleEntity(entity || {})
   const lname = target.name as ExampleLang
-  // The entity's id-like key field name, or null when it has none (a
-  // response-wrapped spec can model an entity with no id). Drives whether the
-  // state example keys on an id at all.
-  const idF = entityIdField(ex)
-  // The entity's PRIMARY op — an op it actually exposes (never a hardcoded
-  // `load` a create-only entity lacks).
-  const primaryOp = entityPrimaryOp(ex) || 'load'
-  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
-  // Type-correct example id literal (numeric when the id param is integer-typed),
-  // derived from the OP's param type so an id carried only in the match compiles.
-  const idLit = idLiteral(ex, primaryOp, idF)
-  // Language-correct call argument for the primary op: a match for load/remove,
-  // a required-field body for create/update, nothing for list.
-  let stateArg: string
-  if ('list' === primaryOp) {
-    stateArg = 'go' === target.name ? 'nil' : ''
-  } else if (isMatchOp) {
-    stateArg = matchArg(lname, idF, idLit)
-  } else {
-    stateArg = dataArg(lname, ex, primaryOp, idF)
+  const hasEntityExample = !!(ex && primaryOp)
+
+  let eName = 'Entity', eLower = 'entity', stateArg = '', matchIdF: string | null = null, idLit = ''
+  if (hasEntityExample) {
+    eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
+    // Sanitise against the target's reserved words (a `Delete` entity must
+    // not bind `const delete = ...`).
+    eLower = safeVarName(eName.toLowerCase(), target.name)
+    const idF = entityIdField(ex)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    // Type-correct example id literal (numeric when the id param is integer-
+    // typed), derived from the OP's param type so an id carried only in the
+    // match compiles.
+    idLit = idLiteral(ex, primaryOp as string, idF)
+    // Language-correct call argument for the primary op: a match for
+    // load/remove, a required-field body for create/update, nothing for list.
+    if ('list' === primaryOp) {
+      stateArg = 'go' === target.name ? 'nil' : ''
+    } else if (isMatchOp) {
+      stateArg = matchArg(lname, idF, idLit)
+    } else {
+      stateArg = dataArg(lname, ex, primaryOp as string, idF)
+    }
+    // Only a match op keys the `.match()` comment on `{ id: ... }`.
+    matchIdF = isMatchOp ? idF : null
   }
-  // Only a match op keys the `.match()` comment on `{ id: ... }`.
-  const matchIdF = isMatchOp ? idF : null
 
   Content(`
 ## Advanced
@@ -327,12 +328,13 @@ were added, so later features can override earlier ones.
   }
 
 
-  // Entity state
-  Content(`### Entity state
+  // Entity state — only when the SDK actually has an entity op to show.
+  if (hasEntityExample) {
+    Content(`### Entity state
 
 `)
-
-  Content(lang.entityState(eName, eLower, primaryOp, stateArg, matchIdF, idLit))
+    Content(lang.entityState(eName, eLower, primaryOp as string, stateArg, matchIdF, idLit))
+  }
 
 
   // Direct vs entity access

package/src/cmp/ReadmeTop.ts

@@ -25,6 +25,7 @@ import {
 
 
 const SDKGEN_REPO = 'https://github.com/voxgig/sdkgen'
+const VOXGIG_SDK = 'https://voxgig.com/sdk/'
 
 
 // A type-correct TS example literal for a model field, keyed off its canonical
@@ -97,6 +98,16 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
     `[${apiWebsite.replace(/^https?:\/\//, '').replace(/\/$/, '')}](${apiWebsite}).`
     : ''
 
+  // Attribution for API metadata sourced from a third-party catalogue (e.g.
+  // freepublicapis.com). Rendered only when the model carries an
+  // `info.meta_source` URL, so first-party SDKs never show it. The link points
+  // back to the catalogue that kindly supplied the metadata.
+  const metaSource = (info.meta_source || '').trim()
+  const metaSourceLine = metaSource
+    ? `Meta data kindly supplied by ` +
+    `[${metaSource.replace(/^https?:\/\//, '').replace(/\/$/, '')}](${metaSource}).`
+    : ''
+
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const target = getModelPath(model, `main.${KIT}.target`)
   const feature = getModelPath(model, `main.${KIT}.feature`)
@@ -118,16 +129,25 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
   const docsOrder: string[] = (getModelPath(model, `main.${KIT}.config.docs_order`,
     { only_active: false, required: false }) as any) || []
 
+  const orderOf = (name: string): number => {
+    const i = docsOrder.indexOf(name)
+    if (i !== -1) return i
+    // Unlisted targets go after the languages; keep the CLI then MCP last.
+    if (name === 'go-cli') return docsOrder.length + 1
+    if (name === 'go-mcp') return docsOrder.length + 2
+    return docsOrder.length
+  }
+
   const sdkTargets = activeTargets
     .filter((t: any) => t.name !== 'go-cli' && t.name !== 'go-mcp')
     .slice()
-    .sort((a: any, b: any) => {
-      const ai = docsOrder.indexOf(a.name)
-      const bi = docsOrder.indexOf(b.name)
-      const av = ai === -1 ? docsOrder.length : ai
-      const bv = bi === -1 ? docsOrder.length : bi
-      return av - bv
-    })
+    .sort((a: any, b: any) => orderOf(a.name) - orderOf(b.name))
+
+  // Every installable port for the Packages table — including the go-cli and
+  // go-mcp binaries, which publish as Go modules via git tags.
+  const pkgTargets = activeTargets
+    .slice()
+    .sort((a: any, b: any) => orderOf(a.name) - orderOf(b.name))
 
   const langList = sdkTargets.map((t: any) => t.title).join(', ')
   const leadTarget = pickLeadTarget(sdkTargets)
@@ -153,7 +173,14 @@ ${tagline}
     }
     Content(`${nonAffiliation(model)}
 
+Learn more about Voxgig SDKs at [voxgig.com/sdk](${VOXGIG_SDK}).
+
+`)
+    if (metaSourceLine) {
+      Content(`${metaSourceLine}
+
 `)
+    }
 
     // Positioning line, only when we actually have multiple SDK targets.
     if (sdkTargets.length > 1) {
@@ -242,19 +269,43 @@ rather than reasoning about raw HTTP routes and query parameters.
 `)
     }
 
+    // 2c. Offline unit testing — a headline feature: every SDK ships a mock
+    // transport, so it belongs high up, right after the entity model.
+    if (sdkTargets.length > 0) {
+      Content(`## Offline unit testing
+
+Every SDK ships a built-in **test mode** that swaps the HTTP transport for
+an in-memory mock, so your unit tests run fully offline — no server, no
+network, and no credentials:
+
+`)
+      sdkTargets.forEach((tgt: any) => {
+        const Test =
+          requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopTest_${tgt.name}`, { ignore: true })
+        if (Test) {
+          Content(`### ${tgt.title}
+
+`)
+          Test['ReadmeTopTest']({ target: tgt })
+          Content(`
+`)
+        }
+      })
+    }
+
     // 3. Packages — real published package name + install command per
     // ecosystem. A package that is NOT yet live on its registry (the fleet
     // default: 'pending') must NOT advertise a `npm install ...` that 404s —
     // its Install cell links to the git-tag releases page instead. The go
     // family resolves from the tag directly (`go get <mod>@latest`).
-    if (sdkTargets.length > 0) {
+    if (pkgTargets.length > 0) {
       const { releasesUrl } = repoInfo(model)
       Content(`## Packages
 
 | Language | Package | Install |
 | --- | --- | --- |
 `)
-      sdkTargets.forEach((tgt: any) => {
+      pkgTargets.forEach((tgt: any) => {
         const state = registryState(model, tgt.name)
         let cell: string
         if ('active' === state) {
@@ -402,28 +453,6 @@ own list above for exactly which it supports.
       })
     }
 
-    // 9. Testing — keep, but slim
-    if (sdkTargets.length > 0) {
-      Content(`## Unit testing in offline mode
-
-Every SDK ships a test mode that swaps the HTTP transport for an
-in-memory mock, so unit tests run offline.
-
-`)
-      sdkTargets.forEach((tgt: any) => {
-        const Test =
-          requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopTest_${tgt.name}`, { ignore: true })
-        if (Test) {
-          Content(`### ${tgt.title}
-
-`)
-          Test['ReadmeTopTest']({ target: tgt })
-          Content(`
-`)
-        }
-      })
-    }
-
     // 10. Direct and prepare — a common everyday task (the low-level
     // escape hatch for endpoints the entity model doesn't cover).
     Content(`## Direct and prepare

package/src/helpers/naming.ts

@@ -11,8 +11,11 @@
 // 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).
+// rb/py/lua list the keywords that are illegal as a local-variable binding
+// (e.g. a `Self` entity -> `self = client.Self` is a Ruby SyntaxError, an
+// `End` entity -> `end = ...` a Lua one). PHP variables are `$`-prefixed so a
+// lowercased entity name never collides (only `$this` is special, and no
+// entity is named `this`), so PHP is not treated.
 
 const JS_RESERVED = new Set<string>([
   'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
@@ -32,10 +35,37 @@ const GO_RESERVED = new Set<string>([
   'var',
 ])
 
+// Ruby keywords — illegal as a local-variable name (e.g. `self`, `end`).
+const RB_RESERVED = new Set<string>([
+  'alias', 'and', 'begin', 'break', 'case', 'class', 'def', 'defined?',
+  'do', 'else', 'elsif', 'end', 'ensure', 'false', 'for', 'if', 'in',
+  'module', 'next', 'nil', 'not', 'or', 'redo', 'rescue', 'retry', 'return',
+  'self', 'super', 'then', 'true', 'undef', 'unless', 'until', 'when',
+  'while', 'yield', '__FILE__', '__LINE__', '__ENCODING__', 'BEGIN', 'END',
+])
+
+// Python keywords — illegal as a variable name.
+const PY_RESERVED = new Set<string>([
+  'False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await', 'break',
+  'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally',
+  'for', 'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal',
+  'not', 'or', 'pass', 'raise', 'return', 'try', 'while', 'with', 'yield',
+])
+
+// Lua keywords — illegal as a variable name. (`self` is NOT reserved in Lua.)
+const LUA_RESERVED = new Set<string>([
+  'and', 'break', 'do', 'else', 'elseif', 'end', 'false', 'for', 'function',
+  'goto', 'if', 'in', 'local', 'nil', 'not', 'or', 'repeat', 'return',
+  'then', 'true', 'until', 'while',
+])
+
 const RESERVED: Record<string, Set<string>> = {
   ts: JS_RESERVED,
   js: JS_RESERVED,
   go: GO_RESERVED,
+  rb: RB_RESERVED,
+  py: PY_RESERVED,
+  lua: LUA_RESERVED,
 }
 
 

package/src/helpers/opShape.ts

@@ -238,6 +238,93 @@ function entityPrimaryOp(ent: any): string | null {
 }
 
 
+// Collision-free target-language CLASS name for an entity. The natural
+// class name is `<Name>Entity`, but that can equal another entity's
+// canonical DATA-type name `<Name'>` when Name' === Name + 'Entity' (e.g.
+// GitLab's `project` -> class `ProjectEntity` collides with `project_entity`
+// -> data type `ProjectEntity`), which redeclares a type in Go and merges/
+// shadows it in ts/py/rb. This assigns each entity a class name that is
+// unique across ALL emitted top-level type names (every entity's data type
+// and per-op Match/Data types, plus already-assigned class names): the
+// natural `<Name>Entity` when free, else `<Name>EntityClient`, `...Client2`,
+// … The DATA type keeps its canonical `<Name>` — only the suffixed class
+// yields. Deterministic (sorted-key iteration) and stable across runs.
+//
+// Memoised per entity-collection object so the O(n) assignment runs once.
+const _classNameCache = new WeakMap<object, Record<string, string>>()
+
+function entityClassNames(entityColl: any): Record<string, string> {
+  const cached = _classNameCache.get(entityColl)
+  if (null != cached) {
+    return cached
+  }
+
+  const ents = each(entityColl).filter((e: any) => e && e.active !== false)
+
+  // 1. Every top-level DATA-type name the target emits.
+  const taken: Record<string, boolean> = {}
+  ents.forEach((e: any) => {
+    taken[e.Name] = true
+    for (const op of ['load', 'list', 'create', 'update', 'remove']) {
+      if (e.op && e.op[op]) {
+        taken[opTypeName(e.Name, op)] = true
+      }
+    }
+  })
+
+  // 2. Assign each class name, avoiding all data types and prior classes.
+  const out: Record<string, string> = {}
+  ents.forEach((e: any) => {
+    let name = e.Name + 'Entity'
+    if (taken[name]) {
+      const base = name + 'Client'
+      name = base
+      let n = 1
+      while (taken[name]) {
+        n++
+        name = base + n
+      }
+    }
+    taken[name] = true
+    out[e.name] = name
+  })
+
+  _classNameCache.set(entityColl, out)
+  return out
+}
+
+
+// The collision-free class name for one entity (see entityClassNames).
+// `entityColl` is main.<KIT>.entity (the collection the entity belongs to).
+function entityClassName(ent: any, entityColl: any): string {
+  if (null == ent) {
+    return ''
+  }
+  const map = entityClassNames(entityColl)
+  return map[ent.name] || (ent.Name + 'Entity')
+}
+
+
+// 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
+// active op, else the first active entity. Returns { entity, primaryOp }
+// where primaryOp is null only when NO entity has an op — so callers never
+// fabricate an op the entity lacks (the cause of `.load()` on an op-less
+// entity like Cloudsmith's `Abort`). Entities iterate in sorted-key order
+// 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 op = entityPrimaryOp(e)
+    return 'list' === op || 'load' === op
+  })
+  const withOp = actives.find((e: any) => null != entityPrimaryOp(e))
+  const chosen = readable || withOp || actives[0] || null
+  return { entity: chosen, primaryOp: null == chosen ? null : entityPrimaryOp(chosen) }
+}
+
+
 // 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`
@@ -267,6 +354,8 @@ export {
   entityDataIdField,
   entityOps,
   entityPrimaryOp,
+  pickExampleEntity,
+  entityClassName,
 }
 
 export type {

package/src/sdkgen.ts

@@ -48,7 +48,7 @@ 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 } from './helpers/opShape'
+import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName } from './helpers/opShape'
 import { isReservedName, safeVarName } from './helpers/naming'
 import {
   packageName,
@@ -448,6 +448,8 @@ export {
   entityDataIdField,
   entityOps,
   entityPrimaryOp,
+  pickExampleEntity,
+  entityClassName,
   isReservedName,
   safeVarName,