@voxgig/sdkgen 1.2.1 → 1.3.2

package/src/cmp/ReadmeExplanation.ts

@@ -8,322 +8,342 @@ import {
 
 import { requirePath } from '../utility'
 
+import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { idLiteral, matchArg, dataArg } from '../helpers/opExample'
+import type { ExampleLang } from '../helpers/opExample'
+import { safeVarName } from '../helpers/naming'
 
-const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
-  const { target, ctx$ } = props
-  const { model } = ctx$
-
-  const feature = getModelPath(model, `main.${KIT}.feature`)
 
-  Content(`
-## Explanation
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
 
-### The operation pipeline
 
-Every entity operation (load, list, create, update, remove) follows a
-six-stage pipeline. Each stage fires a feature hook before executing:
+// The four sections below differ by target language but share an identical
+// structure, so the per-language prose lives in one table rather than in
+// parallel if/else chains. Targets not listed here (ts, js, ...) use
+// DEFAULT_LANG.
+type LangExplain = {
+  featureKind: string // what a "feature" is in this language
+  // stateful-entity explanation + example, driven by the entity's PRIMARY op
+  // (`op`) — never a hardcoded `load` a create-only entity lacks. `arg` is the
+  // pre-rendered, language-correct call argument; `matchIdF` is the id key when
+  // the op is a match op (so the `.match()` comment shows `{ id: ... }`), else
+  // null (a generic comment).
+  entityState: (
+    eName: string, eLower: string,
+    op: string, arg: string,
+    matchIdF: string | null, idLit: string,
+  ) => string
+  direct: string      // direct/prepare explanation
+}
 
-\`\`\`
-PrePoint \u2192 PreSpec \u2192 PreRequest \u2192 PreResponse \u2192 PreResult \u2192 PreDone
-\`\`\`
 
-- **PrePoint**: Resolves which API endpoint to call based on the
-  operation name and entity configuration.
-- **PreSpec**: Builds the HTTP spec \u2014 URL, method, headers, body \u2014
-  from the resolved point and the caller's parameters.
-- **PreRequest**: Sends the HTTP request. Features can intercept here
-  to replace the transport (as TestFeature does with mocks).
-- **PreResponse**: Parses the raw HTTP response.
-- **PreResult**: Extracts the business data from the parsed response.
-- **PreDone**: Final stage before returning to the caller. Entity
-  state (match, data) is updated here.
+const DEFAULT_LANG: LangExplain = {
+  featureKind: `Features are the extension mechanism. A feature is an object with a
+\`hooks\` map. Each hook key is a pipeline stage name, and the value is
+a function that receives the context.
 
-`)
+`,
+  entityState: (eName, eLower, op, arg, matchIdF, idLit) => `Entity instances are stateful. After a successful \`${op}\`, the entity
+stores the returned data and match criteria internally. Subsequent
+calls on the same instance can rely on this state.
 
-  // Target-specific error description
-  if (target.name === 'py') {
-    Content(`If any stage returns an error, the pipeline short-circuits and the
-error is returned to the caller as the second element in the return tuple.
+\`\`\`ts
+const ${eLower} = client.${eName}()
+await ${eLower}.${op}(${arg})
 
-`)
-  }
-  else if (target.name === 'php') {
-    Content(`If any stage returns an error, the pipeline short-circuits and the
-error is returned to the caller as the second element in the return array.
+// ${eLower}.data() now returns the ${eLower} data from the last \`${op}\`
+${matchIdF ? `// ${eLower}.match() returns { ${matchIdF}: ${idLit} }` : `// ${eLower}.match() returns the last match criteria`}
+\`\`\`
 
-`)
-  }
-  else if (target.name === 'rb') {
-    Content(`If any stage returns an error, the pipeline short-circuits and the
-error is returned to the caller as a second return value.
+Call \`make()\` to create a fresh instance with the same configuration
+but no stored state.
 
-`)
-  }
-  else if (target.name === 'lua') {
-    Content(`If any stage returns an error, the pipeline short-circuits and the
-error is returned to the caller as a second return value.
+`,
+  direct: `The \`direct\` method gives full control over the HTTP request. Use it
+for non-standard endpoints, bulk operations, or any path not modelled
+as an entity. The \`prepare\` method is useful for debugging — it
+shows exactly what \`direct\` would send.
 
-`)
-  }
-  else if (target.name === 'go') {
-    Content(`If any stage returns an error, the pipeline short-circuits and the
-error is returned to the caller. An unexpected panic triggers the
-\`PreUnexpected\` hook.
+`,
+}
 
-`)
-  }
-  else {
-    Content(`If any stage returns an error, the pipeline short-circuits and the
-error is returned to the caller.
 
-An unexpected exception triggers the \`PreUnexpected\` hook before
-propagating.
+const LANGS: Record<string, LangExplain> = {
+  py: {
+    featureKind: `Features are the extension mechanism. A feature is a Python class
+with hook methods named after pipeline stages (e.g. \`PrePoint\`,
+\`PreSpec\`). Each method receives the context.
 
-`)
-  }
+`,
+    entityState: (eName, eLower, op, arg) => `Entity instances are stateful. After a successful \`${op}\`, the entity
+stores the returned data and match criteria internally.
 
+\`\`\`python
+${eLower} = client.${eName}()
+${eLower}.${op}(${arg})
 
-  // Features and hooks
-  Content(`### Features and hooks
+# ${eLower}.data_get() now returns the ${eLower} data from the last ${op}
+# ${eLower}.match_get() returns the last match criteria
+\`\`\`
 
-`)
+Call \`make()\` to create a fresh instance with the same configuration
+but no stored state.
 
-  if (target.name === 'py') {
-    Content(`Features are the extension mechanism. A feature is a Python class
-with hook methods named after pipeline stages (e.g. \`PrePoint\`,
-\`PreSpec\`). Each method receives the context.
+`,
+    direct: `\`direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare()\` builds the request without sending it — useful
+for debugging or custom transport.
 
-`)
-  }
-  else if (target.name === 'php') {
-    Content(`Features are the extension mechanism. A feature is a PHP class
-with hook methods named after pipeline stages (e.g. \`PrePoint\`,
-\`PreSpec\`). Each method receives the context.
+`,
+  },
 
-`)
-  }
-  else if (target.name === 'rb') {
-    Content(`Features are the extension mechanism. A feature is a Ruby class
+  php: {
+    featureKind: `Features are the extension mechanism. A feature is a PHP class
 with hook methods named after pipeline stages (e.g. \`PrePoint\`,
 \`PreSpec\`). Each method receives the context.
 
-`)
-  }
-  else if (target.name === 'lua') {
-    Content(`Features are the extension mechanism. A feature is a Lua table
-with hook methods named after pipeline stages (e.g. \`PrePoint\`,
-\`PreSpec\`). Each method receives the context.
+`,
+    entityState: (eName, eLower, op, arg) => `Entity instances are stateful. After a successful \`${op}\`, the entity
+stores the returned data and match criteria internally.
 
-`)
-  }
-  else if (target.name === 'go') {
-    Content(`Features are the extension mechanism. A feature implements the
-\`Feature\` interface and provides hooks \u2014 functions keyed by pipeline
-stage names.
+\`\`\`php
+$${eLower} = $client->${eName}();
+$${eLower}->${op}(${arg});
 
-`)
-  }
-  else {
-    Content(`Features are the extension mechanism. A feature is an object with a
-\`hooks\` map. Each hook key is a pipeline stage name, and the value is
-a function that receives the context.
+// $${eLower}->data_get() now returns the ${eLower} data from the last ${op}
+// $${eLower}->match_get() returns the last match criteria
+\`\`\`
 
-`)
-  }
+Call \`make()\` to create a fresh instance with the same configuration
+but no stored state.
 
-  Content(`The SDK ships with built-in features:
+`,
+    direct: `\`direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare()\` builds the request without sending it — useful
+for debugging or custom transport.
 
-`)
-  each(feature, (feat: any) => {
-    if (!feat.active) return
-    if (!feat.Name) names(feat, feat.name)
-    const purpose = feat.title || feat.Name || feat.name
-    Content(`- **${feat.Name}Feature**: ${purpose}
-`)
-  })
+`,
+  },
 
-  Content(`
-Features are initialized in order. Hooks fire in the order features
-were added, so later features can override earlier ones.
+  rb: {
+    featureKind: `Features are the extension mechanism. A feature is a Ruby class
+with hook methods named after pipeline stages (e.g. \`PrePoint\`,
+\`PreSpec\`). Each method receives the context.
 
-`)
+`,
+    entityState: (eName, eLower, op, arg) => `Entity instances are stateful. After a successful \`${op}\`, the entity
+stores the returned data and match criteria internally.
 
+\`\`\`ruby
+${eLower} = client.${eName}
+${eLower}.${op}(${arg})
 
-  // Target-specific explanation
-  const ReadmeExplanation_sdk =
-    requirePath(ctx$, `./cmp/${target.name}/ReadmeExplanation_${target.name}`, { ignore: true })
+# ${eLower}.data_get now returns the ${eLower} data from the last ${op}
+# ${eLower}.match_get returns the last match criteria
+\`\`\`
 
-  if (ReadmeExplanation_sdk) {
-    ReadmeExplanation_sdk['ReadmeExplanation']({ target })
-  }
+Call \`make\` to create a fresh instance with the same configuration
+but no stored state.
 
+`,
+    direct: `\`direct\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare\` builds the request without sending it — useful
+for debugging or custom transport.
 
-  // Entity state
-  Content(`### Entity state
+`,
+  },
 
-`)
+  lua: {
+    featureKind: `Features are the extension mechanism. A feature is a Lua table
+with hook methods named after pipeline stages (e.g. \`PrePoint\`,
+\`PreSpec\`). Each method receives the context.
 
-  if (target.name === 'py') {
-    Content(`Entity instances are stateful. After a successful \`load\`, the entity
+`,
+    entityState: (eName, eLower, op, arg) => `Entity instances are stateful. After a successful \`${op}\`, the entity
 stores the returned data and match criteria internally.
 
-\`\`\`python
-moon = client.Moon()
-moon.load({"planet_id": "earth", "id": "luna"})
+\`\`\`lua
+local ${eLower} = client:${eName}()
+${eLower}:${op}(${arg})
 
-# moon.data_get() now returns the loaded moon data
-# moon.match_get() returns the last match criteria
+-- ${eLower}:data_get() now returns the ${eLower} data from the last ${op}
+-- ${eLower}:match_get() returns the last match criteria
 \`\`\`
 
 Call \`make()\` to create a fresh instance with the same configuration
 but no stored state.
 
-`)
-  }
-  else if (target.name === 'php') {
-    Content(`Entity instances are stateful. After a successful \`load\`, the entity
-stores the returned data and match criteria internally.
+`,
+    direct: `\`direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`prepare()\` builds the request without sending it — useful
+for debugging or custom transport.
 
-\`\`\`php
-$moon = $client->Moon();
-[$result, $err] = $moon->load(["planet_id" => "earth", "id" => "luna"]);
+`,
+  },
 
-// $moon->dataGet() now returns the loaded moon data
-// $moon->matchGet() returns the last match criteria
-\`\`\`
-
-Call \`make()\` to create a fresh instance with the same configuration
-but no stored state.
+  go: {
+    featureKind: `Features are the extension mechanism. A feature implements the
+\`Feature\` interface and provides hooks — functions keyed by pipeline
+stage names.
 
-`)
-  }
-  else if (target.name === 'rb') {
-    Content(`Entity instances are stateful. After a successful \`load\`, the entity
+`,
+    entityState: (eName, eLower, op, arg) => `Entity instances are stateful. After a successful \`${cap(op)}\`, the entity
 stores the returned data and match criteria internally.
 
-\`\`\`ruby
-moon = client.Moon
-moon.load({ "planet_id" => "earth", "id" => "luna" })
+\`\`\`go
+${eLower} := client.${eName}(nil)
+${eLower}.${cap(op)}(${arg}, nil)
 
-# moon.data_get now returns the loaded moon data
-# moon.match_get returns the last match criteria
+// ${eLower}.Data() now returns the ${eLower} data from the last ${op}
+// ${eLower}.Match() returns the last match criteria
 \`\`\`
 
-Call \`make\` to create a fresh instance with the same configuration
+Call \`Make()\` to create a fresh instance with the same configuration
 but no stored state.
 
-`)
-  }
-  else if (target.name === 'lua') {
-    Content(`Entity instances are stateful. After a successful \`load\`, the entity
-stores the returned data and match criteria internally.
+`,
+    direct: `\`Direct()\` gives full control over the HTTP request. Use it for
+non-standard endpoints, bulk operations, or any path not modelled as
+an entity. \`Prepare()\` builds the request without sending it — useful
+for debugging or custom transport.
 
-\`\`\`lua
-local moon = client:Moon(nil)
-moon:load({ planet_id = "earth", id = "luna" }, nil)
+`,
+  },
+}
 
--- moon:data_get() now returns the loaded moon data
--- moon:match_get() returns the last match criteria
-\`\`\`
 
-Call \`make()\` to create a fresh instance with the same configuration
-but no stored state.
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
 
-`)
+  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.
+  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 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)
   }
-  else if (target.name === 'go') {
-    Content(`Entity instances are stateful. After a successful \`Load\`, the entity
-stores the returned data and match criteria internally.
+  // Only a match op keys the `.match()` comment on `{ id: ... }`.
+  const matchIdF = isMatchOp ? idF : null
 
-\`\`\`go
-moon := client.Moon(nil)
-moon.Load(map[string]any{"planet_id": "earth", "id": "luna"}, nil)
+  Content(`
+## Advanced
 
-// moon.Data() now returns the loaded moon data
-// moon.Match() returns the last match criteria
-\`\`\`
+> The sections above cover everyday use. The material below explains the
+> SDK's internals — useful when extending it with custom features, but not
+> needed for normal use.
 
-Call \`Make()\` to create a fresh instance with the same configuration
-but no stored state.
+### The operation pipeline
 
-`)
-  }
-  else {
-    Content(`Entity instances are stateful. After a successful \`load\`, the entity
-stores the returned data and match criteria internally. Subsequent
-calls on the same instance can rely on this state.
+Every entity operation follows a six-stage pipeline. Each stage fires a
+feature hook before executing:
 
-\`\`\`ts
-const moon = client.Moon()
-await moon.load({ planet_id: 'earth', id: 'luna' })
-
-// moon.data() now returns the loaded moon data
-// moon.match() returns { planet_id: 'earth', id: 'luna' }
+\`\`\`
+PrePoint → PreSpec → PreRequest → PreResponse → PreResult → PreDone
 \`\`\`
 
-Call \`make()\` to create a fresh instance with the same configuration
-but no stored state.
+- **PrePoint**: Resolves which API endpoint to call based on the
+  operation name and entity configuration.
+- **PreSpec**: Builds the HTTP spec — URL, method, headers, body —
+  from the resolved point and the caller's parameters.
+- **PreRequest**: Sends the HTTP request. Features can intercept here
+  to replace the transport (as TestFeature does with mocks).
+- **PreResponse**: Parses the raw HTTP response.
+- **PreResult**: Extracts the business data from the parsed response.
+- **PreDone**: Final stage before returning to the caller. Entity
+  state (match, data) is updated here.
 
-`)
-  }
+If any stage errors, the pipeline short-circuits and the error surfaces
+to the caller — see [Error handling](#error-handling) for how that looks
+in this language.
 
+`)
 
-  // Direct vs entity access
-  Content(`### Direct vs entity access
 
-The entity interface handles URL construction, parameter placement,
-and response parsing automatically. Use it for standard CRUD operations.
+  // Features and hooks
+  Content(`### Features and hooks
 
 `)
 
-  if (target.name === 'py') {
-    Content(`\`direct()\` gives full control over the HTTP request. Use it for
-non-standard endpoints, bulk operations, or any path not modelled as
-an entity. \`prepare()\` builds the request without sending it \u2014 useful
-for debugging or custom transport.
+  Content(lang.featureKind)
 
-`)
-  }
-  else if (target.name === 'php') {
-    Content(`\`direct()\` gives full control over the HTTP request. Use it for
-non-standard endpoints, bulk operations, or any path not modelled as
-an entity. \`prepare()\` builds the request without sending it \u2014 useful
-for debugging or custom transport.
+  Content(`The SDK ships with built-in features:
 
 `)
-  }
-  else if (target.name === 'rb') {
-    Content(`\`direct\` gives full control over the HTTP request. Use it for
-non-standard endpoints, bulk operations, or any path not modelled as
-an entity. \`prepare\` builds the request without sending it \u2014 useful
-for debugging or custom transport.
-
+  each(feature, (feat: any) => {
+    if (!feat.active) return
+    if (!feat.Name) names(feat, feat.name)
+    const purpose = feat.title || feat.Name || feat.name
+    Content(`- **${feat.Name}Feature**: ${purpose}
 `)
-  }
-  else if (target.name === 'lua') {
-    Content(`\`direct()\` gives full control over the HTTP request. Use it for
-non-standard endpoints, bulk operations, or any path not modelled as
-an entity. \`prepare()\` builds the request without sending it \u2014 useful
-for debugging or custom transport.
+  })
+
+  Content(`
+Features are initialized in order. Hooks fire in the order features
+were added, so later features can override earlier ones.
 
 `)
+
+
+  // Target-specific explanation
+  const ReadmeExplanation_sdk =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeExplanation_${target.name}`, { ignore: true })
+
+  if (ReadmeExplanation_sdk) {
+    ReadmeExplanation_sdk['ReadmeExplanation']({ target })
   }
-  else if (target.name === 'go') {
-    Content(`\`Direct()\` gives full control over the HTTP request. Use it for
-non-standard endpoints, bulk operations, or any path not modelled as
-an entity. \`Prepare()\` builds the request without sending it \u2014 useful
-for debugging or custom transport.
+
+
+  // Entity state
+  Content(`### Entity state
 
 `)
-  }
-  else {
-    Content(`The \`direct\` method gives full control over the HTTP request. Use it
-for non-standard endpoints, bulk operations, or any path not modelled
-as an entity. The \`prepare\` method is useful for debugging \u2014 it
-shows exactly what \`direct\` would send.
+
+  Content(lang.entityState(eName, eLower, primaryOp, stateArg, matchIdF, idLit))
+
+
+  // Direct vs entity access
+  Content(`### Direct vs entity access
+
+The entity interface handles URL construction, parameter placement,
+and response parsing automatically. Use it for standard CRUD operations.
 
 `)
-  }
+
+  Content(lang.direct)
 
 })
 

package/src/cmp/ReadmeModel.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from 'jostraca'
+import { cmp, each, names, Content } from 'jostraca'
 
 import {
   KIT,
@@ -13,6 +13,10 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
+  // Guard the Name case variant so the reference header never renders
+  // "undefinedSDK" if apidef did not populate it.
+  if (model.name && !model.Name) names(model, model.name)
+
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
@@ -60,7 +64,8 @@ ${apikeyRow}| \`base\` | \`string\` | Base URL of the API server. |
 `)
 
   each(entityList, (ent: any) => {
-    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
 `)
   })