@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/clojure/TestEntity_clojure.ts

@@ -0,0 +1,79 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+// Emit per-entity model-driven checks INTO the shared gentest run body (the
+// clojure test runner drives a single sdk.gentest/run). Covers: entity
+// accessor existence, a create+list smoke run through the in-memory test-mode
+// mock transport (exercising the full operation pipeline, hooks and run-op),
+// and the streaming entity fn. API-agnostic behaviour (pipeline error
+// branches, all features, netsim, primary utility, struct corpus) lives in the
+// static template test namespaces.
+const TestEntity = cmp(function TestEntity(props: any) {
+  const e = props.entity
+
+  const ops = Object.keys(e.op || {})
+  const hasCreate = ops.includes('create')
+  const hasList = ops.includes('list')
+
+  // Accessor existence.
+  Content(`  (t/run-check rec "gen-exists-${e.name}"
+    (fn [] (let [sdk (api/test-sdk nil nil)]
+             (t/is-true (some? (api/${e.name} sdk nil)) "${e.name} accessor present"))))
+`)
+
+  // create+list smoke run through the mock transport.
+  if (hasCreate || hasList) {
+    Content(`  (t/run-check rec "gen-smoke-${e.name}"
+    (fn [] (let [sdk (api/test-sdk nil nil)
+                 ent (api/${e.name} sdk nil)]
+`)
+    if (hasCreate) {
+      Content(`             (let [res (e-${e.name}/create ent (vs/jm "name" "smoke") nil)]
+               (t/is-true (vs/ismap res) "create returns a record map")
+               (t/is-true (some? (vs/getprop res "id")) "created record has an id"))
+`)
+    }
+    if (hasList) {
+      Content(`             (let [items (e-${e.name}/list ent (vs/jm) nil)]
+               (t/is-true (sequential? items) "list returns a sequential collection"))
+`)
+    }
+    Content(`             )))
+`)
+  }
+
+  // stream(action, args, callopts): runs the op through the full pipeline and
+  // returns a lazy seq of items. Seeds three records via the test mock and
+  // streams them; needs only a list op.
+  if (hasList) {
+    Content(`  (t/run-check rec "gen-stream-${e.name}"
+    (fn [] (let [seed (vs/jm "${e.name}" (vs/jm "S1" (vs/jm "id" "S1" "name" "a")
+                                                "S2" (vs/jm "id" "S2" "name" "b")
+                                                "S3" (vs/jm "id" "S3" "name" "c")))]
+             ;; Fallback (no streaming feature): materialised items.
+             (let [sdk (api/test-sdk (vs/jm "entity" seed) nil)
+                   items (vec (e-${e.name}/stream (api/${e.name} sdk nil) "list" (vs/jm) nil))]
+               (t/is-eq (count items) 3 "stream fallback yields materialised items")
+               (t/is-true (vs/ismap (first items)) "stream yields bare record maps"))
+             ;; signal cancels iteration between yields.
+             (let [sdk (api/test-sdk (vs/jm "entity" seed) nil)
+                   n (atom 0) sig (fn [] (>= (swap! n inc) 2))
+                   items (vec (e-${e.name}/stream (api/${e.name} sdk nil) "list" (vs/jm) (vs/jm "signal" sig)))]
+               (t/is-eq (count items) 1 "stream signal stops after first yield"))
+             ;; Streaming feature active: yields from the streaming iterator.
+             (when (vs/getpath (config/make-config) "feature.streaming")
+               (let [ssdk (api/test-sdk (vs/jm "entity" seed) (vs/jm "feature" (vs/jm "streaming" (vs/jm "active" true))))]
+                 (t/is-eq (count (vec (e-${e.name}/stream (api/${e.name} ssdk nil) "list" (vs/jm) nil))) 3
+                          "stream (streaming active) yields all items"))
+               (let [csdk (api/test-sdk (vs/jm "entity" seed) (vs/jm "feature" (vs/jm "streaming" (vs/jm "active" true "chunkSize" 2))))
+                     batches (vec (e-${e.name}/stream (api/${e.name} csdk nil) "list" (vs/jm) nil))]
+                 (t/is-eq (count batches) 2 "stream chunkSize groups items into 2 batches"))))))
+`)
+  }
+})
+
+
+export {
+  TestEntity
+}

package/project/.sdk/src/cmp/clojure/Test_clojure.ts

@@ -10,20 +10,24 @@ import type {
 
 import { cmp, each, File, Content, Folder } from '@voxgig/sdkgen'
 
+import { TestEntity } from './TestEntity_clojure'
+import { TestDirect } from './TestDirect_clojure'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_clojure'
+
 
 // Generates sdk/gentest.clj (ns sdk.gentest): the API-specific tests, driven by
-// the model. Exposes (run rec) which the template test-runner invokes. Covers
-// entity accessor existence plus a create+list smoke run through the in-memory
-// test-mode mock transport (exercising the full operation pipeline, hooks and
-// run-op for the actual API entities). API-agnostic behaviour (pipeline error
-// branches, all features, netsim, primary utility, struct corpus) lives in the
-// static template test namespaces.
+// the model. Exposes (run rec) which the template test-runner invokes. This is
+// the orchestrator: it emits the namespace form and the single (run rec) entry
+// point, then delegates the per-entity checks to TestEntity (accessor +
+// create/list smoke + stream) and TestDirect (prepare + direct escape hatch),
+// and finally the documentation clojure-examples syntax gate (ReadmeExamples).
+// API-agnostic behaviour (pipeline error branches, all features, netsim,
+// primary utility, struct corpus) lives in the static template test namespaces.
 const Test = cmp(function Test(props: any) {
   const { model } = props.ctx$
   const { target } = props
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const entities = Object.values(entity) as any[]
 
   Folder({ name: 'test' }, () => {
     Folder({ name: 'sdk' }, () => {
@@ -39,73 +43,25 @@ const Test = cmp(function Test(props: any) {
   (:require [sdk.api :as api]
             [sdk.config :as config]
             [sdk.testutil :as t]
+            [clojure.string]
             [voxgig.struct :as vs]${requires}))
 
 (defn run [rec]
 `)
 
+        // Per-entity accessor / create+list smoke / stream checks
+        // (sorted-key order via each() keeps output byte-stable).
         each(entity, (e: any) => {
-          Content(`  (t/run-check rec "gen-exists-${e.name}"
-    (fn [] (let [sdk (api/test-sdk nil nil)]
-             (t/is-true (some? (api/${e.name} sdk nil)) "${e.name} accessor present"))))
-`)
+          TestEntity({ target, entity: e })
         })
 
-        for (const e of entities) {
-          const ops = Object.keys(e.op || {})
-          const hasCreate = ops.includes('create')
-          const hasList = ops.includes('list')
-          if (!hasCreate && !hasList) {
-            continue
-          }
-          Content(`  (t/run-check rec "gen-smoke-${e.name}"
-    (fn [] (let [sdk (api/test-sdk nil nil)
-                 ent (api/${e.name} sdk nil)]
-`)
-          if (hasCreate) {
-            Content(`             (let [res (e-${e.name}/create ent (vs/jm "name" "smoke") nil)]
-               (t/is-true (vs/ismap res) "create returns a record map")
-               (t/is-true (some? (vs/getprop res "id")) "created record has an id"))
-`)
-          }
-          if (hasList) {
-            Content(`             (let [items (e-${e.name}/list ent (vs/jm) nil)]
-               (t/is-true (sequential? items) "list returns a sequential collection"))
-`)
-          }
-          Content(`             )))
-`)
+        // Per-entity direct()/prepare() escape-hatch checks.
+        each(entity, (e: any) => {
+          TestDirect({ target, entity: e })
+        })
 
-          // PR review #4: entity stream(action, args, callopts). Runs the op
-          // through the full pipeline and returns a lazy seq of items. Seeds
-          // three records via the test mock (SDK.test entity seed) and streams
-          // them; needs only a list op.
-          if (hasList) {
-            Content(`  (t/run-check rec "gen-stream-${e.name}"
-    (fn [] (let [seed (vs/jm "${e.name}" (vs/jm "S1" (vs/jm "id" "S1" "name" "a")
-                                                "S2" (vs/jm "id" "S2" "name" "b")
-                                                "S3" (vs/jm "id" "S3" "name" "c")))]
-             ;; Fallback (no streaming feature): materialised items.
-             (let [sdk (api/test-sdk (vs/jm "entity" seed) nil)
-                   items (vec (e-${e.name}/stream (api/${e.name} sdk nil) "list" (vs/jm) nil))]
-               (t/is-eq (count items) 3 "stream fallback yields materialised items")
-               (t/is-true (vs/ismap (first items)) "stream yields bare record maps"))
-             ;; signal cancels iteration between yields.
-             (let [sdk (api/test-sdk (vs/jm "entity" seed) nil)
-                   n (atom 0) sig (fn [] (>= (swap! n inc) 2))
-                   items (vec (e-${e.name}/stream (api/${e.name} sdk nil) "list" (vs/jm) (vs/jm "signal" sig)))]
-               (t/is-eq (count items) 1 "stream signal stops after first yield"))
-             ;; Streaming feature active: yields from the streaming iterator.
-             (when (vs/getpath (config/make-config) "feature.streaming")
-               (let [ssdk (api/test-sdk (vs/jm "entity" seed) (vs/jm "feature" (vs/jm "streaming" (vs/jm "active" true))))]
-                 (t/is-eq (count (vec (e-${e.name}/stream (api/${e.name} ssdk nil) "list" (vs/jm) nil))) 3
-                          "stream (streaming active) yields all items"))
-               (let [csdk (api/test-sdk (vs/jm "entity" seed) (vs/jm "feature" (vs/jm "streaming" (vs/jm "active" true "chunkSize" 2))))
-                     batches (vec (e-${e.name}/stream (api/${e.name} csdk nil) "list" (vs/jm) nil))]
-                 (t/is-eq (count batches) 2 "stream chunkSize groups items into 2 batches"))))))
-`)
-          }
-        }
+        // Documentation clojure-examples syntax gate.
+        ReadmeExamplesTest({ target })
 
         Content(`  nil)
 `)

package/project/.sdk/src/cmp/cpp/EntityTypes_cpp.ts

@@ -0,0 +1,174 @@
+
+
+// Typed-model generator (C++ target). Port of EntityTypes_ts.ts / _py.ts.
+//
+// The C++ SDK runtime is fully DYNAMIC: every op takes and returns the
+// JSON-like sdk::Value, so — unlike a statically typed target — there are no
+// generated structs the runtime consumes. This module emits a DOCUMENTATION
+// header, <sdk>_types.hpp, describing the shape of each entity and its per-op
+// request/match payloads as plain C++ structs in a dedicated `sdk::types`
+// namespace. They are convenience/reference types a consumer MAY use to model
+// payloads; the SDK itself neither includes nor requires this header, so it is
+// safe (it cannot affect the runtime or the test build).
+//
+// Field/param sentinels ($STRING, $INTEGER, ...) map to concrete C++ types via
+// the SHARED canonToType 'cpp' column (the single source of truth per language
+// — do not keep a local table here). Array surfaces as std::vector<Value>,
+// object as std::map<std::string, Value>, and any/null/unknown as the dynamic
+// sdk::Value. Optional (req:false) members are marked with a trailing
+// `// optional` comment — a struct member is always present in C++, so
+// key-optionality is documented rather than encoded.
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch (via the shared opTypeName helper).
+
+import {
+  cmp, each, names,
+  File, Content,
+  canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions,
+  deriveEntityNames,
+} from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'cpp'
+
+
+// A valid C++ identifier for a struct member; non-identifier field names have
+// no safe struct-member rendering, so they are skipped (still reachable via the
+// runtime Value map).
+function cppIdent(name: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)
+}
+
+
+// Emit a struct named `typeName` from a list of {name, type, optional} items.
+// An item whose name is not a legal identifier is skipped (WITH a warning —
+// the key stays reachable via the runtime Value map, but its absence from the
+// typed model should be visible, not silent).
+function emitStruct(typeName: string, items: any[], log?: any): void {
+  const usable = items.filter((it: any) => it && null != it.name && cppIdent(it.name))
+
+  items.forEach((it: any) => {
+    if (it && null != it.name && !cppIdent(it.name) && log && log.warn) {
+      log.warn({
+        point: 'entity-types-skip-field', typeName, field: it.name,
+        note: `cpp: field "${it.name}" of ${typeName} has no legal C++ ` +
+          `identifier form; omitted from the typed model (still reachable ` +
+          `via the runtime Value map)`,
+      })
+    }
+  })
+
+  if (0 === usable.length) {
+    Content(`struct ${typeName} {};
+
+`)
+    return
+  }
+
+  Content(`struct ${typeName} {
+`)
+  usable.forEach((it: any) => {
+    const opt = it.optional ? '  // optional' : ''
+    Content(`  ${canonToType(it.type, LANG)} ${it.name};${opt}
+`)
+  })
+  Content(`};
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model, log } = props.ctx$
+  const target = props.target || {}
+  const ext = target.ext || 'hpp'
+
+  // 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().
+
+  // 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)
+
+  const guard = 'SDK_' + model.const.Name.toUpperCase().replace(/[^A-Z0-9]/g, '_') + '_TYPES_HPP'
+
+  File({ name: model.const.Name.toLowerCase() + '_types.' + ext }, () => {
+
+    Content(`// Typed reference models for the ${model.const.Name} SDK (C++).
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params. The C++ SDK runtime is Value-based, so these structs are
+// DOCUMENTATION / convenience types only — the SDK neither includes nor
+// requires this header. Array fields surface as std::vector<Value>, object
+// fields as std::map<std::string, Value>, and any/null fields as sdk::Value.
+// Optional (req:false) members are flagged with a trailing "// optional"
+// comment. Do not edit by hand.
+
+#ifndef ${guard}
+#define ${guard}
+
+#include <cstdint>
+#include <map>
+#include <string>
+#include <vector>
+
+#include "core/types.hpp"
+
+namespace sdk {
+namespace types {
+
+`)
+
+    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 member per field, `req:false` -> optional.
+      emitStruct(Name, fields.map((f: any) => ({
+        name: f.name, type: f.type, optional: false === f.req,
+      })), log)
+
+      // Per active op: a request/match type. 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, items, log)
+      })
+    })
+
+    Content(`} // namespace types
+} // namespace sdk
+
+#endif // ${guard}
+`)
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/cpp/Entity_cpp.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 {
@@ -20,7 +20,7 @@ const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
 
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
   const entrep = {
@@ -33,7 +33,7 @@ const Entity = cmp(function Entity(props: any) {
 
     File({ name: cppVarName(entity.name) + '.' + target.ext }, () => {
 
-      const opnames = Object.keys(entity.op)
+      const opnames = Object.keys(entity.op || {})
 
       // For each CRUD op: splice the real method if the spec defines it, else
       // a stub that satisfies the SdkEntity interface but throws at runtime.

package/project/.sdk/src/cmp/cpp/MainEntity_cpp.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -16,7 +16,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 accessor = cppVarName(entity.name)
 

package/project/.sdk/src/cmp/cpp/Main_cpp.ts

@@ -23,6 +23,7 @@ import { Config } from './Config_cpp'
 import { Gitignore } from './Gitignore_cpp'
 import { MainEntity } from './MainEntity_cpp'
 import { EntityBase } from './EntityBase_cpp'
+import { EntityTypes } from './EntityTypes_cpp'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -49,6 +50,10 @@ const Main = cmp(async function Main(props: any) {
   // entity/entities.hpp — the entity umbrella (declares every entity header).
   EntityBase({ target })
 
+  // <sdk>_types.hpp — documentation/reference structs (not used by the
+  // Value-based runtime; safe convenience types for consumers).
+  EntityTypes({ target })
+
   Folder({ name: 'core' }, () => {
 
     Config({ target })

package/project/.sdk/src/cmp/cpp/ReadmeEntity_cpp.ts

@@ -0,0 +1,170 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cppVarName } from './utility_cpp'
+
+
+// Type names come from the shared canonToType 'cpp' column (single source of truth).
+
+// A type-correct C++ literal for a field's canonical type.
+function cppLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
+  if ('BOOLEAN' === k) return 'Value(true)'
+  if ('ARRAY' === k) return 'vlist()'
+  if ('OBJECT' === k) return 'vmap()'
+  return `Value("${placeholder}")`
+}
+
+
+// Operation method spellings for the C++ target: lowercase methods that take a
+// request Value plus the ctrl Value, returning sdk::Value.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match, ctrl)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(match, ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(data, ctrl)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data, ctrl)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match, 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 || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // The client accessor is the entity's snake_case name (client->planet()).
+    const acc = cppVarName(entity.name)
+    const eVar = acc
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`auto ${eVar} = client->${acc}();\`
+
+`)
+
+    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')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from.
+      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
+        ? `vmap({${loadItems.map((it: any) =>
+          `{"${it.name}", ${cppLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}}`).join(', ')}})`
+        : 'Value::undef()'
+      Content(`#### Example: Load
+
+\`\`\`cpp
+Value ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`cpp
+Value ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`cpp
+Value ${eVar} = client->${acc}()->create(vmap({
+`)
+      createItems.map((it: any) => {
+        Content(`    {"${it.name}", ${cppLit(it.type, 'example_' + it.name)}},  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`}), Value::undef());
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}