@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/c/ReadmeTopQuick_c.ts

@@ -0,0 +1,104 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+// A type-correct C expression constructing a voxgig struct Value for a param.
+// Strings render the quoted placeholder; numeric/boolean/array/object render a
+// typed builder call.
+function cLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
+  if ('BOOLEAN' === k) return 'v_bool(true)'
+  if ('ARRAY' === k) return 'v_list()'
+  if ('OBJECT' === k) return 'v_map()'
+  return `v_str("${placeholder}")`
+}
+
+
+// cmap(...) for a set of `"key", <lit>` pairs, or NULL when empty (ops accept
+// a NULL match/data argument).
+function cmapExpr(pairs: string[]): string {
+  return pairs.length ? `cmap(${pairs.length}, ${pairs.join(', ')})` : 'NULL'
+}
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const ident = cIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `${ident}_sdk_new(cmap(1,\n    "apikey", v_str(getenv("${envName(model)}_APIKEY"))))`
+    : `${ident}_sdk_new(NULL)`
+
+  Content(`\`\`\`c
+#include "core/api.h"
+
+${model.const.Name}SDK* client = ${ctor};
+PNError* err = NULL;
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const evar = cVarName(exampleEntity.name)
+    const acc = `${ident}_${evar}`
+    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.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`Entity* ${evar} = ${acc}(client, NULL);
+
+// List all ${eName.toLowerCase()}s (returns a List, sets *err on failure)
+voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
+    printf("%s\\n", voxgig_to_json(voxgig_getelem(${evar}s, v_int(i), NULL)));
+}
+`)
+    }
+
+    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 loadItems = opRequestShape(exampleEntity, '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 = cmapExpr(loadItems.map((it: any) =>
+        `"${it.name}", ${cLit(it.type,
+          it.name === idF ? 'example_id' : 'example_' + it.name)}`))
+      const acquire = opnames.includes('list')
+        ? ''
+        : `Entity* ${evar} = ${acc}(client, NULL);\n`
+      Content(`
+${acquire}// Load a specific ${eName.toLowerCase()} (returns the record, sets *err on failure)
+voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+printf("%s\\n", voxgig_to_json(${evar}_rec));
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/c/ReadmeTopTest_c.ts

@@ -0,0 +1,86 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+// A type-correct C expression constructing a voxgig struct Value for a field's
+// canonical type.
+function cLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
+  if ('BOOLEAN' === k) return 'v_bool(true)'
+  if ('ARRAY' === k) return 'v_list()'
+  if ('OBJECT' === k) return 'v_map()'
+  return 'v_str("example")'
+}
+
+
+// cmap(...) for a set of pairs, or NULL when empty.
+function cmapExpr(pairs: string[]): string {
+  return pairs.length ? `cmap(${pairs.length}, ${pairs.join(', ')})` : 'NULL'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const ident = cIdent(model)
+  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.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`c
+#include "core/api.h"
+
+${model.const.Name}SDK* client = test_sdk(NULL, NULL);
+PNError* err = NULL;
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eName = nom(exampleEntity, 'Name')
+    const evar = cVarName(exampleEntity.name)
+    const acc = `${ident}_${evar}`
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'NULL'
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's request match.
+      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))
+      arg = cmapExpr(items.map((it: any) =>
+        `"${it.name}", ${it.name === idF ? 'v_str("test01")' : cLit(it.type)}`))
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      arg = cmapExpr(chosen.map((it: any) => `"${it.name}", ${cLit(it.type)}`))
+    }
+    const resVar = cVarName(exampleEntity.name) + ('list' === primaryOp ? 's' : '_rec')
+    Content(`Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* ${resVar} = ${evar}->vt->${primaryOp}(${evar}, ${arg}, NULL, &err);
+printf("%s\\n", voxgig_to_json(${resVar}));
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/c/TestDirect_c.ts

@@ -64,15 +64,15 @@ const TestDirect = cmp(function TestDirect(props: any) {
   const evar = cVarName(entity.name)
   const Name = model.const.Name
 
-  const opnames = Object.keys(entity.op)
+  const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
   if (!hasLoad && !hasList) {
     return
   }
 
-  const loadOp = (entity.op as any).load
-  const listOp = (entity.op as any).list
+  const loadOp = (entity.op as any)?.load
+  const listOp = (entity.op as any)?.list
 
   const loadPoint = loadOp?.points?.[0]
   const loadPath = loadPoint ? normalizePathParams(loadPoint.parts || [], loadPoint?.args?.params || [], loadPoint?.rename?.param) : ''

package/project/.sdk/src/cmp/c/TestEntity_c.ts

@@ -39,7 +39,14 @@ int main(void) {
   Entity* e = ${ident}_${evar}(sdk, NULL);
   CHECK(e != NULL, "entity instance");
   CHECK_STR_EQ(e->vt->get_name(e), "${entity.name}", "entity get_name");
+`)
 
+    // The stream test drives the list op; only emit it when the entity has a
+    // list op — a create/load-only entity has no list endpoint, so
+    // stream("list") would error.
+    const hasList = null != (entity.op && (entity.op as any)?.list)
+    if (hasList) {
+      Content(`
   // stream(): runs the list op through the full pipeline and returns a List
   // of items. Seed two entities via test mode; with the streaming feature
   // active it yields the feature's incremental items, else it falls back to
@@ -69,7 +76,10 @@ int main(void) {
     CHECK(perr == NULL, "stream fallback: no error");
     CHECK_INT_EQ((int64_t)voxgig_as_list(pitems)->len, 2, "stream fallback: yields both items");
   }
+`)
+    }
 
+    Content(`
   TEST_SUMMARY("${evar}_entity");
 }
 `)

package/project/.sdk/src/cmp/c/Test_c.ts

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_c'
 import { TestDirect } from './TestDirect_c'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_c'
 
 
 const Test = cmp(function Test(props: any) {
@@ -42,6 +43,9 @@ int main(void) {
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // Validate the documented C examples in the READMEs are well-formed.
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/c/utility_c.ts

@@ -23,9 +23,15 @@ function cVarName(name: string): string {
 }
 
 
-// The C project identifier used as a function-name prefix, e.g. solar.
+// The C project identifier used as a function-name prefix, e.g. solar. Must
+// match the SQUASHED `projectname` token that the umbrella header/fragment use
+// for the constructor (`<ident>_sdk_new`): a hyphenated slug
+// (bluefin-decryptx-p2pe) squashes to `bluefindecryptxp2pe`, so drop every
+// non-alphanumeric char rather than mapping them to `_` (which produced
+// `bluefin_decryptx_p2pe_sdk_new` callers that never linked against the
+// squashed definition). No-op for single-word names.
 function cIdent(model: any): string {
-  return String(model.name).toLowerCase().replace(/[^a-z0-9_]/g, '_')
+  return String(model.name).toLowerCase().replace(/[^a-z0-9]/g, '')
 }
 
 

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

@@ -31,7 +31,7 @@ const Entity = cmp(function Entity(props: any) {
 
         File({ name: entity.name + '.' + target.ext }, () => {
 
-          const opnames = Object.keys(entity.op)
+          const opnames = Object.keys(entity.op || {})
 
           // For each CRUD op: splice the real implementation when the spec
           // defines it; otherwise leave the slot empty (the fn is simply not

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

@@ -0,0 +1,182 @@
+
+import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// A type-correct Clojure literal for a field's canonical type. The create
+// example builds a real struct map, so array/object render as (vs/jt)/(vs/jm).
+function cljLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '(vs/jt)'
+  if ('OBJECT' === k) return '(vs/jm)'
+  return `"${placeholder}"`
+}
+
+
+// A descriptive Clojure-ish type name for a field's canonical type. Clojure is
+// dynamically typed, so these are documentation hints, not static types.
+function cljType(type: any): string {
+  const k = canonKey(type)
+  if ('STRING' === k) return 'string'
+  if ('INTEGER' === k) return 'long'
+  if ('NUMBER' === k) return 'double'
+  if ('BOOLEAN' === k) return 'boolean'
+  if ('ARRAY' === k) return 'vector'
+  if ('OBJECT' === k) return 'map'
+  return 'any'
+}
+
+
+// Operation descriptions are language-agnostic; the method spelling matches
+// the generated Clojure entity fns: (op ent arg ctrl).
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: '(load ent match ctrl)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: '(list ent match ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: '(create ent data ctrl)',  desc: 'Create a new entity with the given data.' },
+  update: { method: '(update ent data ctrl)',  desc: 'Update an existing entity.' },
+  remove: { method: '(remove ent 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)
+    const eLow = entity.name
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`(def ${eLow} (api/${eLow} client nil))\`
+
+`)
+
+    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}\` | \`${cljType(field.type)}\` | ${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
+        ? `(vs/jm ${loadItems.map((it: any) =>
+          `"${it.name}" ${cljLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(' ')})`
+        : 'nil'
+      Content(`#### Example: Load
+
+\`\`\`clojure
+(def ${eLow} (e-${eLow}/load (api/${eLow} client nil) ${loadArg} nil))
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`clojure
+(def ${eLow}s (e-${eLow}/list (api/${eLow} client nil) nil nil))
+\`\`\`
+
+`)
+    }
+
+    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
+
+\`\`\`clojure
+(def ${eLow}
+  (e-${eLow}/create (api/${eLow} client nil)
+    (vs/jm
+`)
+      createItems.map((it: any) => {
+        Content(`      "${it.name}" ${cljLit(it.type, 'example_' + it.name)}  ;; ${cljType(it.type)}
+`)
+      })
+      Content(`      )
+    nil))
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

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

@@ -0,0 +1,65 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+// Emit a documentation clojure-examples SYNTAX gate INTO the shared gentest run
+// body (the clojure test runner drives a single sdk.gentest/run). For each doc
+// that ships clojure examples — the repository ROOT README.md, the per-language
+// README.md, and REFERENCE.md — every ```clojure fenced block is extracted and
+// PARSED with read-string (all forms wrapped in a vector), catching a malformed
+// documented example (an unbalanced paren, a bad token, an unclosed string).
+//
+// SCOPE NOTE: like the elixir gate, this stops at the syntax check rather than
+// EXECUTING each block. Running a README fragment against the generated
+// namespaces would need the SDK loaded and the narrative requires resolved for
+// every block; the syntax gate is a real, useful guard that keeps documented
+// examples parseable as the generator evolves. A doc that is absent at test
+// time is skipped (passes), so the gate never hard-fails on a missing file.
+//
+// The emitted clojure builds the triple-backtick fence from (char 96) so this
+// TS template literal needs no embedded backticks.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(_props: any) {
+
+  Content(`  (letfn [(fence-pat [] (re-pattern (apply str (repeat 3 (char 96)))))
+          (fence-count [text] (count (re-seq (fence-pat) text)))
+          (clj-blocks [text]
+            (let [parts (clojure.string/split text (fence-pat))]
+              (->> parts
+                   (map-indexed vector)
+                   (filter (fn [[i _]] (odd? i)))
+                   (map (fn [[_ seg]] seg))
+                   (filter (fn [seg]
+                             (= "clojure"
+                                (clojure.string/trim (first (clojure.string/split-lines seg))))))
+                   (map (fn [seg]
+                          (clojure.string/join "\\n"
+                            (rest (clojure.string/split-lines seg))))))))]
+    (doseq [[label path] [["root-README" "../README.md"]
+                          ["README" "README.md"]
+                          ["REFERENCE" "REFERENCE.md"]]]
+      (t/run-check rec (str "gen-readme-examples-" label)
+        (fn []
+          (if-not (.exists (java.io.File. ^String path))
+            (t/is-true true (str label " absent (skipped)"))
+            (let [text (slurp path)]
+              ;; A code fence opened but never closed leaves an ODD number of
+              ;; fence markers; the split-on-fence then captures the trailing
+              ;; prose (everything after the last opener) as if it were a
+              ;; clojure block, which can parse cleanly and pass silently. Fail
+              ;; on the malformed doc instead. (Count markers directly rather
+              ;; than split parts: split drops trailing empty segments, so a
+              ;; closing fence at EOF would be miscounted.)
+              (t/is-true (even? (fence-count text))
+                         (str label " code fences balanced (no unclosed fence)"))
+              (let [blocks (clj-blocks text)]
+                (doseq [b blocks]
+                  (binding [*read-eval* false]
+                    (read-string (str "[\\n" b "\\n]"))))
+                (t/is-true true (str label " clojure blocks parse cleanly")))))))))
+`)
+})
+
+
+export {
+  ReadmeExamplesTest
+}

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

@@ -0,0 +1,44 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as struct value maps
+
+The Clojure SDK represents API data with the vendored \`voxgig.struct\`
+value model (ordered, Java-backed maps and lists) rather than typed
+records. This mirrors the dynamic nature of the API and keeps the SDK
+flexible — no code generation is needed when the API schema changes.
+
+Build request maps with \`(vs/jm "k" v ...)\` and lists with
+\`(vs/jt v ...)\`; read values with \`(vs/getprop m "k")\`. Use
+\`(vs/ismap x)\` to safely check that a value is a map.
+
+### Namespace structure
+
+\`\`\`
+${target.name}/
+├── src/sdk/api.clj        -- public API namespace (entity accessors)
+├── src/sdk/client.clj     -- client constructors (make-sdk, test-sdk)
+├── src/sdk/config.clj     -- generated configuration
+├── src/sdk/core.clj       -- core types, context and pipeline
+├── src/sdk/features.clj   -- feature factory
+├── src/sdk/entity/        -- entity namespaces (one per entity)
+├── src/voxgig/struct.clj  -- vendored struct value library
+└── test/                  -- test suites
+\`\`\`
+
+Require \`[sdk.api :as api]\` for the public surface, and an entity
+namespace (e.g. \`[sdk.entity.${model.const.Name.toLowerCase()} :as e-${model.const.Name.toLowerCase()}]\`)
+only when you call its operations directly.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}