@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/rb/EntityTypes_rb.ts

@@ -1,29 +1,5 @@
 
 
-// Typed-model generator (Ruby target).
-//
-// Ported from the TypeScript reference EntityTypes_ts.ts. Reads
-// main.<KIT>.entity.<e>.fields[] and per-op params (op.<name>.points[].args.params[])
-// and emits one file, <Sdk>_types.rb, containing a keyword-init Struct per active
-// entity plus a request/match Struct per active op. Ruby has no enforced static
-// types, so each member carries a YARD `@!attribute`/`@return` annotation whose
-// element type comes from the canonical sentinels via the shared sdkgen helper
-// `canonToType` (source of truth: @voxgig/apidef VALID_CANON):
-//   $STRING -> String, $INTEGER -> Integer, $NUMBER -> Float, $BOOLEAN -> Boolean,
-//   $OBJECT -> Hash, $ARRAY -> Array, unknown -> Object.
-//
-// Type-name scheme (as TS, with one Ruby-only guard): data type = <Name>,
-// except where Ruby core already owns that constant — `File`, `Time`, `Data`,
-// … — which would be silently REPLACED by the assignment; those become
-// <Name>Type (see rbSafeTypeName). Per-op request
-// <Name>LoadMatch / <Name>ListMatch / <Name>RemoveMatch (query/id ops),
-// <Name>CreateData / <Name>UpdateData (body ops). An op WITH params -> a Struct of
-// those params (reqd:false -> annotated `[Type, nil]`). An op WITHOUT params -> a
-// Struct over the entity fields (Struct members are always optional/nil, so this is
-// the Ruby stand-in for TS `Partial<Name>`; callers may equally pass a plain Hash).
-//
-// Struct.new(keyword_init: true) gives value objects usable as `Advice.new(id: ...)`.
-// The file is required by the main SDK module so these constants are always loaded.
 
 import {
   cmp, each, names,
@@ -47,17 +23,6 @@ function symName(name: string): string {
 }
 
 
-// Emit one typed value class: a YARD @!attribute block plus a keyword-init
-// Struct. Ruby's `Struct.new` rejects zero members, so an empty shape falls
-// back to a plain empty class (keeps the type name available).
-//
-// A member with an EMPTY name is dropped first. `Struct.new(:"")` raises
-// `NameError: cannot make operator ID : attrset` when the file loads, which
-// takes the whole SDK down rather than just that type -- and quoting does
-// not help, since the empty symbol is the one Ruby will not accept (`:"a-b"`
-// and `:"1x"` are both fine). A model should not carry a nameless field, so
-// upstream is where it gets fixed; this keeps one bad field from costing the
-// target everything.
 function emitStruct(
   typeName: string,
   doc: string,
@@ -92,24 +57,12 @@ function emitStruct(
 const EntityTypes = cmp(function EntityTypes(props: any) {
   const { model, log } = props.ctx$
 
-  // only_active:false — getModelPath DROPS active:false entries by default,
-  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
-  // collection, so inactive entities still get generated entity code that
-  // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  // Emit for EVERY entity that gets generated entity code: the consumer
-  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
-  // filter, so inactive entities still get class files referencing these
-  // typed names. Filter on `name` (always present), NOT `active` — parity
-  // with the go emitter's fix.
   const entityList = deriveEntityNames(entity)
   // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   File({ name: model.const.Name + '_types.' + LANG }, () => {
@@ -118,8 +71,8 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
 # Typed models for the ${model.const.Name} SDK.
 #
-# GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
-# params (op.<name>.points[].args.params[]). Member types come from the
+# GENERATED from the API model: main.${KIT}.entity.<e>.fields{} and per-op
+# params (op.<name>.points[].g.params[]). Member types come from the
 # canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
 # @voxgig/apidef VALID_CANON). Ruby types are unenforced; these YARD
 # annotations document the shapes. Do not edit by hand.
@@ -128,27 +81,16 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
     entityList.forEach((ent: any) => {
       const Name = ent.Name
-      // Ruby constants share ONE namespace with the core classes, and
-      // assigning one silently replaces it — an entity named `File` emitting
-      // `File = Struct.new(...)` clobbers ::File and every later `File.join`
-      // raises NoMethodError. Only the bare data-type constant needs the
-      // guard; the per-op names below always carry a suffix that no core
-      // constant matches. The `client.File(...)` accessor is a METHOD, a
-      // separate namespace, so the public surface is unchanged.
       const TypeName = rbSafeTypeName(Name)
       const fields = (ent.fields ? each(ent.fields) : [])
-        .filter((f: any) => f.active !== false)
+        .filter((f: any) => f.a !== false)
 
-      // Entity data model: one member per field (`req:false` -> nilable).
       emitStruct(
         TypeName,
         `${Name} entity data model.`,
-        fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req })),
+        fields.map((f: any) => ({ name: f.n, type: f.t, optional: false === f.r })),
       )
 
-      // Per active op: a request/match Struct. Members and their optionality
-      // come from the shared partiality policy (opRequestShape); this file only
-      // renders them as a keyword-init Struct.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {

package/project/.sdk/src/cmp/rb/Entity_rb.ts

@@ -33,7 +33,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/rb/fragment/')
 
-  // Entity files go to entity/ folder
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.' + target.ext }, () => {
@@ -56,8 +55,6 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.rb so the class can be renamed independently.
           EntyClass: cls,
 
           // Feature-hook markers. jostraca's built-in `#Name-Tag` pattern is

package/project/.sdk/src/cmp/rb/Main_rb.ts

@@ -59,7 +59,6 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // Generate main SDK file
   File({ name: model.const.Name + '_sdk.' + target.ext }, () => {
 
     Fragment(
@@ -83,7 +82,6 @@ utility.feature_hook.call(@_rootctx, "${name}")
         }
       },
 
-      // Entities - injected at SLOT
       () => {
         each(entity, (entity: ModelEntity) => {
           const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -93,19 +91,11 @@ utility.feature_hook.call(@_rootctx, "${name}")
       })
   })
 
-  // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
     Schema({ target })
   })
 
-  // GENERATED, NOT COPIED. Where the credential goes is a fact about the
-  // API, and tm/ can only hold one answer. See PrepareAuth_rb.
-  //
-  // At the TARGET ROOT, not inside the `.` folder above and not inside any
-  // `src`: rb's tree is flat (utility/, core/, feature/ sit at the root),
-  // the component opens the one `utility` folder it needs, and that
-  // reproduces tm/rb/utility/prepare_auth.rb's old path exactly.
   PrepareAuth({ target })
 
   // Generate typed models (<Sdk>_types.rb) — required by the main SDK file.

package/project/.sdk/src/cmp/rb/Package_rb.ts

@@ -28,9 +28,6 @@ const Package = cmp(async function Package(props: any) {
   // constant here did.
   const author = authorInfo(model, target.name)
 
-  // Gem name is namespaced to model.origin (e.g. "voxgig-sdk"). RubyGems
-  // names can't contain "/", so the parts are hyphen-joined. The require
-  // path (`${model.name}_sdk`) is unchanged.
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const gemName = packageName(model, target.name)
@@ -39,7 +36,6 @@ const Package = cmp(async function Package(props: any) {
   const versionOf = (d: { version: string; source: 'feature' | 'target' }) =>
     d.source === 'target' ? (d.version || '0.0') : d.version
 
-  // Generate Gemfile
   File({ name: 'Gemfile' }, () => {
     Content(`source "https://rubygems.org"
 
@@ -53,7 +49,6 @@ gemspec
     }
   })
 
-  // Generate gemspec
   File({ name: model.const.Name + '_sdk.gemspec' }, () => {
     // RubyGems rejects a gemspec that declares the same runtime dependency
     // twice (Gem::InvalidSpecificationException at `gem build`), so the

package/project/.sdk/src/cmp/rb/PrepareAuth_rb.ts

@@ -16,28 +16,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated.
-//
-// This was a static file at `tm/rb/utility/prepare_auth.rb` that hardcoded
-// `HEADER_AUTH = "authorization"`. apidef has always resolved the scheme's
-// `in` and `name` into `main.kit.info.security` — joplin's says
-// `in: "query", name: "token"` — and generation dropped both. The result
-// was an SDK that sent a header the API does not read and never sent the
-// query parameter it does, so it could not authenticate at all. Four repos
-// in the cedar fleet shipped that way: joplin (`token`), pipedrive
-// (`api_token`), trello (`key`), lm-umbrella (`apiKey`).
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value that is fixed at
-// generation time.
-//
-// The ts port is the reference (cmp/ts/PrepareAuth_ts.ts). Two things are
-// deliberately NOT the same here, both recorded at their site below: the
-// header name is lower-cased, and the cookie clear removes our own pair
-// instead of a header that was never set.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -47,17 +25,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const name = resolveAuthName(model)
   const basic = isHttpBasicAuth(model)
 
-  // RB'S LAYOUT IS FLAT, WHICH IS WHY THIS FOLDER IS OPENED HERE AND THE TS
-  // PORT OPENS NONE. In ts, Main wraps its whole body in
-  // `Folder({name:'src'})` and the utilities live at `src/utility/`, so a
-  // second `src` there would write `src/src/utility/`. Main_rb opens no such
-  // folder: `Package`, `Gitignore`, the SDK file and `Copy({from:'tm/rb'})`
-  // all land at the target root, and `Config` sits inside a `Folder({name:
-  // '.'})` that is the root too. The template this replaces was
-  // `tm/rb/utility/prepare_auth.rb`, and that Copy's root IS the target root,
-  // so the file it produced was `<root>/utility/prepare_auth.rb`. One folder,
-  // `utility`, reproduces exactly that path — and register.rb's
-  // `require_relative 'prepare_auth'` (from `utility/`) only resolves there.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({ Name: model.const.Name, active, where, name, basic }))
@@ -101,22 +68,8 @@ end
   // mean something.
   const basicHere = spec.basic && 'header' === spec.where
 
-  // The constant keeps the template's name per placement, so a
-  // header-based SDK regenerates the file it already had.
   const CRED = query ? 'QUERY_AUTH' : cookie ? 'COOKIE_AUTH' : 'HEADER_AUTH'
 
-  // HEADER NAMES ARE LOWER-CASED; QUERY AND COOKIE NAMES ARE NOT.
-  //
-  // `resolveAuthName` answers 'Authorization' by default, but the whole rb
-  // runtime spells header names in lower case — the template's
-  // `HEADER_AUTH = "authorization"`, secrets_feature.rb's
-  // `headers["authorization"]`, debug_feature.rb's mask list. A Ruby Hash key
-  // is case-sensitive, so emitting "Authorization" here would leave the
-  // secrets feature writing a SECOND, separate header and the copied
-  // pipeline_test.rb assertions on `headers["authorization"]` failing. HTTP
-  // header names are case-insensitive on the wire, so lower-casing costs
-  // nothing. Query parameter and cookie names ARE case-sensitive (`?Token=`
-  // is not `?token=`), so those go in verbatim.
   const credName = query || cookie ? spec.name : spec.name.toLowerCase()
 
   const consts =
@@ -140,10 +93,6 @@ end
     : `    headers = spec.headers
 `
 
-  // Removing OUR pair, not the whole cookie header. The ts port deletes
-  // `headers[CRED_name]` for the cookie case, which is a header nothing ever
-  // set — so a stale cookie survives a withdrawn credential there. This
-  // splits the header, drops the one pair we own, and puts the rest back.
   const dropCookie = !cookie ? '' : `
     # Our own pair, and only ours: another cookie the caller set survives.
     drop_cookie = ->(hs) {
@@ -209,9 +158,6 @@ end
 // The one thing that actually differs between placements: where the
 // credential is written, and whether the prefix travels with it.
 function place(where: string, clear: string): string {
-  // NO PREFIX IN A QUERY STRING. `?token=Bearer%20abc` is not a thing any
-  // API reads; the prefix is a header convention and is dropped here
-  // deliberately rather than silently concatenated.
   if ('query' === where) {
     return `
     if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
@@ -244,7 +190,6 @@ function place(where: string, clear: string): string {
 `
   }
 
-  // HEADER: the template's body, unchanged.
   return `
     if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
       ${clear}
@@ -259,30 +204,6 @@ function place(where: string, clear: string): string {
 }
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py port found
-// this first; same reasoning, same fix).
-//
-// `isAuthActive` is false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`). That is a statement about the DEFINITION,
-// not a ban on ever sending a credential: apidef writes it for every spec
-// with no securitySchemes block, and those SDKs are still expected to honour
-// an `apikey` the caller passes. The template placed the credential
-// unconditionally, so they did.
-//
-// Gating the body on `isAuthActive` therefore does not trim dead code, it
-// deletes working authentication. MEASURED, not assumed: with the wider gate
-// this component emitted the no-op for generatedcompile's own fixture
-// (`main: kit: info: { ... auth: false }`) and two running rb lanes went red
-// —
-//
-//   rb: auth null beats an explicit apikey
-//     FAIL: baseline broken: an ordinary apikey was not sent
-//   rb: the secrets feature runs with the feature active
-//     expected the authorization header to carry OPTKEY01, got: nil
-//
-// So the no-op is emitted only when the PROJECT says so: `config.auth.active:
-// false`, an explicit per-SDK switch nobody sets by accident. A spec that is
-// merely silent keeps the credential path it has always had.
 function authSwitchedOn(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -290,8 +211,6 @@ function authSwitchedOn(model: any): boolean {
 }
 
 
-// A Ruby double-quoted literal. `#` is escaped only where it would OPEN an
-// interpolation, matching utility_rb.formatRubyValue.
 function rbstr(s: string): string {
   return '"' + String(s)
     .replace(/\\/g, '\\\\')

package/project/.sdk/src/cmp/rb/ReadmeEntity_rb.ts

@@ -7,9 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct Ruby literal for a field's canonical type — the create body
-// is EXECUTED by the doc test, so it must carry a real value per field.
-// Strings render the quoted placeholder.
 function rbLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -53,8 +50,7 @@ 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 fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     // Sanitise the local variable name — an entity whose lowercased name is a
     // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
@@ -101,8 +97,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
       each(fields, (field: any) => {
-        const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+        const desc = field.sh || ''
+        Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${desc} |
 `)
       })
 
@@ -111,9 +107,6 @@ 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) =>

package/project/.sdk/src/cmp/rb/ReadmeExamplesTest_rb.ts

@@ -7,38 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits test/readme_examples_test.rb — a Minitest COMPLETENESS GATE that
-// guarantees every fenced ruby code example in the package docs is unit-tested.
-// It reads ALL THREE docs — the root (multi-language) ../../README.md, the
-// Ruby-specific ../README.md, and ../REFERENCE.md — extracts every fenced ruby
-// block (tagged by source doc + index) and enforces four properties:
-//
-//   1. SYNTAX — `ruby -c` on every block. Every documented example must parse.
-//   2. RUN — every RUNNABLE block (one that constructs the SDK, drives
-//      client., or performs an entity op) is EXECUTED offline in seeded test
-//      mode against the real SDK. The captured stdout+stderr is scanned for
-//      FATAL programming-error markers REGARDLESS of exit code, so a bug that a
-//      documented begin/rescue swallows and prints is still caught. Only a
-//      not-found / domain error is tolerated.
-//   3. COMPLETENESS — every block is partitioned into exactly one of
-//      {executed, syntaxchecked-nonrunnable, illustration} and the counts must
-//      sum to the total. "illustration" is a NARROW explicit class (a
-//      signature / method-table block that names the SDK class or a documented
-//      method but never uses a live client) — never a catch-all. A
-//      runnable-looking block that was NOT executed lands in neither bucket and
-//      FAILS the gate: no runnable example can be silently skipped.
-//   4. A per-doc summary (total / executed / syntaxchecked / illustration) is
-//      printed.
-//
-// A runnable block is rewritten so its client is a test-mode client
-// (<Sdk>SDK.test) seeded with an in-memory fixture for every entity it
-// references; any real .new/.test constructor is rewritten and the doc's own
-// require of the SDK file is stripped (we require it by absolute path). A block
-// that only *uses* `client` (constructed in an earlier fenced block) gets a
-// test client prepended.
-//
-// The emitted Ruby builds the ``` fence via 96.chr and shells out via Open3,
-// so this generator string contains no backticks of its own.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target } = props
   const { model } = props.ctx$

package/project/.sdk/src/cmp/rb/ReadmeHowto_rb.ts

@@ -8,7 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct Ruby literal for a field's canonical type.
 function rbLit(type: any): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -23,9 +22,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Pick an entity with a real op (prefer a read op) — never fabricate a
-  // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
-  // only when NO entity exposes any op (a direct()-only SDK).
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   // Sanitise the local variable name — an entity whose lowercased name is a
@@ -33,9 +29,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // fixture KEY (`"${eName.toLowerCase()}"`) stays raw — it must match the
   // entity's registered name for the mock lookup to resolve.
   const eVar = exampleVarName(eName.toLowerCase(), 'rb')
-  // Model-driven id key: null when the entity has no id-like field (a
-  // response-wrapped spec). When null the fixture seeds no id and a match op
-  // takes no argument.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   const seedSentence = idF
@@ -44,8 +37,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const testCtor = idF
     ? `${model.const.Name}SDK.test({\n  "entity" => { "${eName.toLowerCase()}" => { "test01" => { "${idF}" => "test01" } } },\n})`
     : `${model.const.Name}SDK.test`
-  // A type-correct argument for the primary-op call: a match hash for load/
-  // remove, a required-field body for create/update, nothing for list.
   let testCallArg = ''
   if (exampleEntity && isMatchOp) {
     const items = opRequestShape(exampleEntity, primaryOp).items

package/project/.sdk/src/cmp/rb/ReadmeModel_rb.ts

@@ -115,13 +115,13 @@ returns a result \`Hash\` with these keys:
 
 `)
   each(entityList, (ent: any) => {
-    const fields = ent.fields || []
+    const fields = Object.values(ent.fields || {})
     const opnames = Object.keys(ent.op || {})
     const ops = ent.op || {}
     const points = each(ops).map((op: any) =>
       op.points ? each(op.points) : []
     ).flat()
-    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+    const path = points.length > 0 ? (points[0] as any).o || '' : ''
 
     Content(`#### ${ent.Name}
 
@@ -129,7 +129,7 @@ returns a result \`Hash\` with these keys:
 | --- | --- |
 `)
     each(fields, (field: any) => {
-      Content(`| \`${field.name}\` | ${field.short || ''} |
+      Content(`| \`${field.n}\` | ${field.sh || ''} |
 `)
     })
 

package/project/.sdk/src/cmp/rb/ReadmeQuick_rb.ts

@@ -47,12 +47,6 @@ client = ${ctor}
     // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
     const eVar = exampleVarName(eName.toLowerCase(), 'rb')
     const opnames = entityOps(exampleEntity)
-    // Model-driven id keys: `idF` is the load-MATCH key (null when the entity
-    // has no id-like field — a response-wrapped spec); when null, load/remove
-    // take no argument. `dataIdF` is the id on the RETURNED record's data type —
-    // an entity can key its match on an id it does not carry as data, so both a
-    // listed record's id column and a `created["id"]` read must be guarded on
-    // this, not the match key.
     const idF = entityIdField(exampleEntity)
     const dataIdF = entityDataIdField(exampleEntity)
 
@@ -72,13 +66,13 @@ client = ${ctor}
     // Model-driven display field: the entity's first non-id string field
     // (falling back to any non-id field), so the list example prints a real
     // column instead of a hardcoded "name" the entity may not have.
-    const fields = exampleEntity.fields || []
+    const fields: any[] = Object.values(exampleEntity.fields || {})
     const displayField =
-      fields.find((f: any) => f && f.name !== 'id' && f.type === '$STRING') ||
-      fields.find((f: any) => f && f.name !== 'id') ||
+      fields.find((f: any) => f && f.n !== 'id' && f.t === '$STRING') ||
+      fields.find((f: any) => f && f.n !== 'id') ||
       null
     const idCol = dataIdF ? `#{item[${JSON.stringify(dataIdF)}]}` : null
-    const dispCol = displayField ? `#{item[${JSON.stringify(displayField.name)}]}` : null
+    const dispCol = displayField ? `#{item[${JSON.stringify(displayField.n)}]}` : null
     const itemPrint = [idCol, dispCol].filter(Boolean).join(' ') || '#{item}'
 
     if (opnames.includes('list')) {
@@ -136,9 +130,6 @@ end
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -164,30 +155,18 @@ end
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields, not a
-    // hardcoded "name" the entity may not have. Literals are Ruby-typed by the
-    // field's canonical type. ids are rendered separately as the match key for
-    // update/remove; a REQUIRED create id stays (the call is invalid without
-    // it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields; update is a patch, so the required
-      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
       return chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type, 'example_' + it.name)}`)
     }
 
-    // The id VALUE for an update/remove match: off the returned `created`
-    // record only when its data type carries the id AND a create ran, else a
-    // type-correct literal (so an update-without-create never references an
-    // undefined `created`).
     const idParamType = (opname: string): any => {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
@@ -216,8 +195,6 @@ client.${eName}.update({ ${updatePairs.join(', ')} })
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/rb/ReadmeRef_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -55,7 +55,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -169,7 +169,7 @@ same parameters as \`direct()\`. Raises on error.
     // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
-      const fields = ent.fields || []
+      const fields = Object.values(ent.fields || {})
       // Model-driven id key: null when this entity has no id-like field, in
       // which case load/remove match on no argument and update omits the id.
       const idF = entityIdField(ent)
@@ -197,7 +197,6 @@ ${eVar} = client.${ent.Name}
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -205,9 +204,9 @@ ${eVar} = client.${ent.Name}
 | --- | --- | --- | --- |
 `)
         each(fields, (field: any) => {
-          const req = field.req ? 'Yes' : 'No'
-          const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
+          const req = field.r ? 'Yes' : 'No'
+          const desc = field.sh || ''
+          Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -234,7 +233,7 @@ ${eVar} = client.${ent.Name}
               if (fop.active === false) return '-'
               return 'Yes'
             })
-            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+            Content(`| \`${field.n}\` | ${cols.join(' | ')} |
 `)
           })
 
@@ -244,7 +243,6 @@ ${eVar} = client.${ent.Name}
       }
 
 
-      // Operation details
       if (opnames.length > 0) {
         Content(`### Operations
 
@@ -260,7 +258,6 @@ ${info.desc}
 
 `)
 
-          // Show example
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
             // like page_id) — the same shape the runtime resolves path
@@ -329,7 +326,6 @@ ${updateLines}  # Fields to update
       }
 
 
-      // Common methods
       Content(`### Common Methods
 
 #### \`data_get -> Hash\`
@@ -361,7 +357,6 @@ Return the entity name.
     })
 
 
-    // Features section
     const activeFeatures = each(feature).filter((f: any) => f.active)
     if (activeFeatures.length > 0) {
       Content(`
@@ -397,9 +392,6 @@ client = ${model.const.Name}SDK.new({
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }