@voxgig/sdkgen 1.3.14 → 1.3.18

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

@@ -39,7 +39,7 @@ gemspec
 
 `)
 
-    for (const d of collectDeps(model, target.name, target.deps)) {
+    for (const d of collectDeps(model, target.name, target.deps, ctx$.log)) {
       Content(`gem "${d.name}", "~> ${versionOf(d)}"
 `)
     }
@@ -51,7 +51,7 @@ gemspec
     // twice (Gem::InvalidSpecificationException at `gem build`), so the
     // unconstrained json fallback is only emitted when the model's own
     // dependency list doesn't already declare json.
-    const deps = collectDeps(model, target.name, target.deps)
+    const deps = collectDeps(model, target.name, target.deps, ctx$.log)
     const hasJson = deps.some((d: any) => 'json' === d.name)
 
     Content(`Gem::Specification.new do |spec|

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -58,7 +58,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     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.
-    const eVar = safeVarName(entity.name, 'rb')
+    const eVar = exampleVarName(entity.name, 'rb')
 
     Content(`
 ### ${entity.Name}

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -32,7 +32,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code. The
   // fixture KEY (`"${eName.toLowerCase()}"`) stays raw — it must match the
   // entity's registered name for the mock lookup to resolve.
-  const eVar = safeVarName(eName.toLowerCase(), 'rb')
+  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.
@@ -48,7 +48,12 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // remove, a required-field body for create/update, nothing for list.
   let testCallArg = ''
   if (exampleEntity && isMatchOp) {
-    testCallArg = idF ? `{ "${idF}" => "test01" }` : ''
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => !it.optional || it.name === idF)
+      .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+    testCallArg = 0 < items.length
+      ? `{ ${items.map((it: any) => `"${it.name}" => ${it.name === idF ? '"test01"' : rbLit(it.type)}`).join(', ')} }`
+      : ''
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -45,7 +45,7 @@ client = ${ctor}
     const article = /^[aeiou]/i.test(eName) ? "an" : "a"
     // Sanitise the local variable name — an entity whose lowercased name is a
     // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
-    const eVar = safeVarName(eName.toLowerCase(), 'rb')
+    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
@@ -102,7 +102,7 @@ end
     if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
       const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
-      const neVar = safeVarName(neName.toLowerCase(), 'rb')
+      const neVar = exampleVarName(neName.toLowerCase(), 'rb')
 
       // Model-driven match: every REQUIRED load-match key — the same shape
       // the runtime resolves path params from, so the example always works.

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -174,7 +174,7 @@ same parameters as \`direct()\`. Raises on error.
       const idF = entityIdField(ent)
       // Sanitise the local variable name — an entity whose lowercased name is
       // a Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
-      const eVar = safeVarName(ent.name, 'rb')
+      const eVar = exampleVarName(ent.name, 'rb')
 
       Content(`
 ---

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -45,7 +45,7 @@ client = ${ctor}
     const eName = nom(exampleEntity, 'Name')
     // Sanitise the local variable name — an entity whose lowercased name is a
     // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
-    const eVar = safeVarName(eName.toLowerCase(), 'rb')
+    const eVar = exampleVarName(eName.toLowerCase(), 'rb')
     const opnames = Object.keys(exampleEntity.op || {})
     // Model-driven id key: null when the entity has no id-like field, in which
     // case the load example takes no match argument.

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -59,7 +59,7 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
     // base name — an entity whose lowercased name is a Ruby keyword (e.g.
     // `self`) would otherwise emit uncompilable code. The fixture KEY (`ename`)
     // stays raw so the mock lookup resolves.
-    const eVar = safeVarName(ename, 'rb') + ('list' === primaryOp ? 's' : '')
+    const eVar = exampleVarName(ename, 'rb') + ('list' === primaryOp ? 's' : '')
     Content(`\`\`\`ruby
 # Seed fixture data so offline calls resolve without a live server.
 client = ${model.const.Name}SDK.test({

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

@@ -70,7 +70,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     ? `\n      "apikey" => env["${PROJECTNAME}_APIKEY"],`
     : ''
 
-  const opnames = Object.keys(entity.op)
+  const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
 
@@ -78,8 +78,8 @@ const TestDirect = cmp(function TestDirect(props: any) {
     return
   }
 
-  const loadOp = entity.op.load
-  const listOp = entity.op.list
+  const loadOp = entity.op?.load
+  const listOp = entity.op?.list
 
   const loadPoint = loadOp?.points?.[0]
   const loadPath = loadPoint ? normalizePathParams(loadPoint.parts || [], loadPoint?.args?.params || [], loadPoint?.rename?.param) : ''

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

@@ -24,6 +24,7 @@ import {
   buildIdNames,
   getMatchEntries,
   isAuthActive,
+  entityDataIdField,
 } from '@voxgig/sdkgen'
 
 
@@ -49,7 +50,7 @@ const TestEntity = cmp(function TestEntity(props: any) {
   // it only applies to entities that declare a list op. Others (e.g. Batch =
   // create/load) have no list endpoint — make_point errors and the stream
   // yields nothing — so skip the stream test for them.
-  const hasList = !!(entity.op && (entity.op as any).list)
+  const hasList = !!(entity.op && (entity.op as any)?.list)
 
   const basicflow: ModelEntityFlow | undefined =
     getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
@@ -327,6 +328,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
 const generateList: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
+  const hasDataId = null != entityDataIdField(entity)
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
@@ -371,7 +373,7 @@ const generateList: OpGen = (ctx, step, index) => {
       const hasRefData = validRef && allSteps.some((s: any) => 'create' === s.op &&
         ((s.input.ref ?? entity.name + '_ref01') === validRef))
 
-      if ('ItemExists' === validator.apply && hasRefData) {
+      if ('ItemExists' === validator.apply && hasRefData && hasDataId) {
         const refDataVar = validRef + '_data'
         Content(`
     found_item = Vs.select(
@@ -379,7 +381,7 @@ const generateList: OpGen = (ctx, step, index) => {
       { "id" => ${refDataVar}["id"] })
     assert !Vs.isempty(found_item)
 `)
-      } else if ('ItemNotExists' === validator.apply && hasRefData) {
+      } else if ('ItemNotExists' === validator.apply && hasRefData && hasDataId) {
         const refDataVar = validRef + '_data'
         Content(`
     not_found_item = Vs.select(
@@ -529,6 +531,9 @@ const generateLoad: OpGen = (ctx, step, index) => {
 
 const generateRemove: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
+  if (null == entityDataIdField(entity)) {
+    return
+  }
   const ref = step.input.ref ?? entity.name + '_ref01'
   const entvar = step.input.entvar ?? ref + '_ent'
   const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))

package/project/.sdk/src/cmp/rust/EntityBase_rust.ts

@@ -5,7 +5,7 @@ import {
   Folder,
   cmp,
   each,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -27,7 +27,7 @@ const EntityBase = cmp(async function EntityBase(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const entityColl = entity
+  const entityColl = entityCollection(model)
 
   Folder({ name: 'entity' }, () => {
     File({ name: 'mod.' + target.ext }, () => {
@@ -39,6 +39,10 @@ const EntityBase = cmp(async function EntityBase(props: any) {
 `)
       })
 
+      // Documentary typed models (entity/types.rs), generated by EntityTypes.
+      Content(`pub mod types;
+`)
+
       if (0 < Object.keys(entity || {}).length) {
         Content(`
 `)

package/project/.sdk/src/cmp/rust/EntityTypes_rust.ts

@@ -0,0 +1,151 @@
+
+
+// Typed-model generator (Rust target). Port of EntityTypes_go.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file, entity/types.rs, with
+// a rust `struct <Name> { ... }` per entity plus a request/match struct per
+// active op. Field/param sentinels ($STRING, $INTEGER, ...) map to rust types
+// via the SHARED canonToType 'rust' column (the single source of truth per
+// language — do not keep a local table here). Note OBJECT renders as
+// std::collections::HashMap<String, Value> (fully qualified, no import
+// needed).
+//
+// DESIGN NOTE (rust specifics vs the go reference):
+//   * The rust runtime is fully DYNAMIC: every op takes and returns the
+//     vendored `Value` enum (Result<Value, ...Error>), and the op fragments
+//     emit no typed wrappers. Go additionally emits `LoadTyped`/`ListTyped`
+//     wrappers plus json round-trip helpers; rust has no serde/json-derive
+//     dependency (only `ureq`), so these typed models are DOCUMENTARY: they
+//     mirror the entity/op shapes for reference and IDE support, but are not
+//     wired into the runtime. They compile as part of the crate (declared in
+//     entity/mod.rs) so they stay in sync with the model.
+//   * Optional (req:false) member -> `Option<T>`.
+//   * The module carries broad `#![allow(...)]` since nothing consumes the
+//     types yet (parity intent, not dead-code churn).
+
+import {
+  cmp, each,
+  File, Content, Folder,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { rustVarName } from './utility_rust'
+
+
+const LANG = 'rust'
+
+
+// One rust struct field line. `optional` -> Option<T>. Field names are
+// snake_case + keyword-safe via rustVarName; duplicates are dropped by the
+// caller so a struct never declares the same field twice.
+function fieldLine(name: string, sentinel: any, optional: boolean): string {
+  const rt = canonToType(sentinel, LANG)
+  const typ = optional ? `Option<${rt}>` : rt
+  return `    pub ${rustVarName(name)}: ${typ},\n`
+}
+
+
+// Emit a struct named `typeName` from {name, type, optional} items, dropping
+// duplicate rust identifiers (two model names can collapse to one ident).
+function emitStruct(comment: string, typeName: string, items: any[]): void {
+  Content(`${comment}
+#[derive(Debug, Clone)]
+pub struct ${typeName} {
+`)
+  const seen = new Set<string>()
+  items.forEach((it: any) => {
+    if (null == it || null == it.name) return
+    const ident = rustVarName(it.name)
+    if (seen.has(ident)) return
+    seen.add(ident)
+    Content(fieldLine(it.name, it.type, !!it.optional))
+  })
+  Content(`}
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { target } = props
+  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 an entity file (filter on `name`, always
+  // present; derive `Name` here so the struct set is deterministic — parity
+  // with the go emitter's fix).
+  const entityList = deriveEntityNames(entity)
+
+  // 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)
+
+  Folder({ name: 'entity' }, () => {
+
+    File({ name: 'types.' + target.ext }, () => {
+
+      Content(`// 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[]). Field/param types are mapped
+// from the canonical type sentinels. Do not edit by hand.
+//
+// These are DOCUMENTARY: the SDK runtime is dynamic (ops take/return the
+// \`Value\` enum), so nothing consumes these structs yet — they mirror the
+// entity/op shapes for reference and IDE support.
+#![allow(dead_code, non_snake_case, unused_imports)]
+
+use crate::utility::voxgigstruct::Value;
+
+`)
+
+      entityList.forEach((ent: any) => {
+        const Name = ent.Name
+        const fields = (ent.fields ? each(ent.fields) : [])
+          .filter((f: any) => f.active !== false)
+
+        // Entity data model: one field per model field. req:false -> Option.
+        emitStruct(
+          `/// ${Name} is the typed data model for the ${ent.name} entity.`,
+          Name,
+          fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req }))
+        )
+
+        // Per active op: a request/match struct. Members and their optionality
+        // come from the shared partiality policy (opRequestShape).
+        const ops = ent.op || {}
+        ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+          if (null == ops[opname]) {
+            return
+          }
+
+          const typeName = opTypeName(Name, opname)
+          const { items } = opRequestShape(ent, opname)
+
+          emitStruct(
+            `/// ${typeName} is the typed request payload for ${Name}.${opname}.`,
+            typeName,
+            items
+          )
+        })
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/rust/Entity_rust.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, camelify,
   File, Content, Folder, Fragment,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 import {
@@ -23,7 +23,7 @@ const Entity = cmp(function Entity(props: any) {
   // Collision-free entity CLASS name (see entityClassName): normally
   // `<Name>Entity`, but disambiguated when it would clash with another
   // entity's data-type name.
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
   const entrep = {
@@ -37,7 +37,7 @@ const Entity = cmp(function Entity(props: any) {
 
     File({ name: rustVarName(entity.name) + '.' + target.ext }, () => {
 
-      const opnames = Object.keys(entity.op)
+      const opnames = Object.keys(entity.op || {})
 
       // For each CRUD op: if the spec defines it, splice in the real
       // implementation. Otherwise emit a stub that satisfies the static
@@ -53,7 +53,7 @@ const Entity = cmp(function Entity(props: any) {
               ({ indent }: any) => {
                 const arg = ('create' === opname || 'update' === opname) ?
                   'reqdata' : 'reqmatch'
-                Content({ indent }, `fn ${opname}(&self, _${arg}: Value, _ctrl: Value) -> Result<Value, ProjectNameError> {
+                Content({ indent }, `fn ${opname}(&self, _${arg}: Value, _ctrl: Value) -> Result<Value, ${model.const.Name}Error> {
     Err(crate::core::helpers::unsupported_op("${opname}", &self.name))
 }
 `)

package/project/.sdk/src/cmp/rust/MainEntity_rust.ts

@@ -1,6 +1,6 @@
 
 
-import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -17,7 +17,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
   const { model } = props.ctx$
 
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
   const method = rustVarName(entity.name)
   const mod = rustVarName(entity.name)

package/project/.sdk/src/cmp/rust/Main_rust.ts

@@ -24,6 +24,7 @@ import { Config } from './Config_rust'
 import { Gitignore } from './Gitignore_rust'
 import { MainEntity } from './MainEntity_rust'
 import { EntityBase } from './EntityBase_rust'
+import { EntityTypes } from './EntityTypes_rust'
 import { SdkError } from './SdkError_rust'
 import { crateIdent } from './utility_rust'
 
@@ -87,6 +88,10 @@ const Main = cmp(async function Main(props: any) {
   // entity/mod.rs — the entity module index.
   EntityBase({ target })
 
+  // entity/types.rs — the documentary typed models (one struct per entity +
+  // per op). Declared as a module by EntityBase so it compiles with the crate.
+  EntityTypes({ target })
+
   // lib.rs — the crate root: module declarations plus the public API
   // re-exports (twin of the go root package file).
   File({ name: 'lib.' + target.ext }, () => {

package/project/.sdk/src/cmp/rust/Package_rust.ts

@@ -43,7 +43,7 @@ path = "lib.rs"
 
     const prod: Record<string, string> = {}
     const dev: Record<string, string> = {}
-    for (const d of collectDeps(model, target.name, target.deps)) {
+    for (const d of collectDeps(model, target.name, target.deps, ctx$.log)) {
       // Target-level deps default to '*' when version is absent; feature
       // deps require an explicit version.
       const version = d.source === 'target' ? (d.version || '*') : d.version

package/project/.sdk/src/cmp/rust/ReadmeEntity_rust.ts

@@ -0,0 +1,163 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { rustVarName } from './utility_rust'
+
+
+// Type names come from the shared canonToType 'rust' column (single source of truth).
+
+// A type-correct rust expression constructing a voxgig struct Value.
+function rustLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
+  if ('BOOLEAN' === k) return 'Value::Bool(true)'
+  if ('ARRAY' === k) return 'Value::empty_list()'
+  if ('OBJECT' === k) return 'Value::empty_map()'
+  return `Value::str("${placeholder}")`
+}
+
+
+// Operation method descriptions (language-agnostic wording, rust signatures).
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(reqmatch, ctrl)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(reqmatch, ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(reqdata, ctrl)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(reqdata, ctrl)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(reqmatch, ctrl)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    const idF = entityIdField(entity)
+    const eVar = rustVarName(entity.name)
+    const method = rustVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`let ${eVar} = client.${method}(Value::Noval);\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `jo(vec![${loadItems.map((it: any) =>
+          `("${it.name}", ${rustLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)})`).join(', ')}])`
+        : 'Value::Noval'
+      Content(`#### Example: Load
+
+\`\`\`rust
+let ${eVar} = client.${method}(Value::Noval).load(${loadArg}, Value::Noval).unwrap();
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`rust
+let ${eVar}s = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`rust
+let ${eVar} = client.${method}(Value::Noval).create(jo(vec![
+`)
+      createItems.map((it: any) => {
+        Content(`    ("${it.name}", ${rustLit(it.type, 'example_' + it.name)}),  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`]), Value::Noval).unwrap();
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}