@voxgig/sdkgen 1.3.14 → 1.3.17

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

@@ -0,0 +1,168 @@
+
+
+// Typed-model generator (C target). Port of EntityTypes_rust.ts / _go.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one header, entity/types.h,
+// with a C `typedef struct { ... } <Name>;` per entity plus a request/match
+// struct per active op. Field/param sentinels ($STRING, $INTEGER, ...) map to
+// C types via the SHARED canonToType 'c' column (the single source of truth
+// per language — do not keep a local table here).
+//
+// DESIGN NOTE (C specifics vs the rust/go reference):
+//   * The C runtime is fully DYNAMIC: every op takes and returns the vendored
+//     `voxgig_value*` (with a trailing PNError** out-param), and the entity
+//     fragments emit no typed wrappers. These structs are therefore
+//     DOCUMENTARY — they mirror the entity/op shapes for reference and IDE
+//     support, but nothing in the runtime consumes them. types.h is a
+//     standalone header (guarded, includes sdk.h for the primitive types); it
+//     is not #included by any generated .c, so it never affects the build.
+//   * C has no Option<T> / optional struct members: a `req:false` field is
+//     still declared, with a trailing `// optional` marker. Absence is
+//     represented at runtime by the value simply not being present in the map.
+//   * Member names are snake_case + keyword-safe via cVarName; duplicate
+//     idents are dropped so a struct never declares the same member twice.
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch.
+
+import {
+  cmp, each, names,
+  File, Content, Folder,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cVarName } from './utility_c'
+
+
+const LANG = 'c'
+
+
+// One C struct member line. `optional` -> a trailing marker (C has no
+// Option<T>). Member names are snake_case + keyword-safe via cVarName.
+function memberLine(name: string, sentinel: any, optional: boolean): string {
+  const ct = canonToType(sentinel, LANG)
+  const sep = ct.endsWith('*') ? '' : ' '
+  return `  ${ct}${sep}${cVarName(name)};${optional ? '  // optional' : ''}\n`
+}
+
+
+// Emit a `typedef struct { ... } <typeName>;` from {name, type, optional}
+// items, dropping duplicate C identifiers (two model names can collapse to
+// one ident). An empty shape gets a placeholder member (a struct with no
+// members is not valid ISO C).
+function emitStruct(comment: string, typeName: string, items: any[]): void {
+  Content(`${comment}
+typedef struct {
+`)
+  const seen = new Set<string>()
+  let count = 0
+  items.forEach((it: any) => {
+    if (null == it || null == it.name) return
+    const ident = cVarName(it.name)
+    if (seen.has(ident)) return
+    seen.add(ident)
+    Content(memberLine(it.name, it.type, !!it.optional))
+    count++
+  })
+  if (0 === count) {
+    Content(`  char _unused;  // placeholder: no modelled members
+`)
+  }
+  Content(`} ${typeName};
+
+`)
+}
+
+
+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 an entity file (filter on `name`, always
+  // present; derive `Name` here so the struct set is deterministic — parity
+  // with the go/rust emitters' fix).
+  const entityList = each(entity).filter((e: any) => e && null != e.name)
+  entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
+
+  // 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 = String(model.const.Name).toUpperCase().replace(/[^A-Z0-9_]/g, '_') + '_ENTITY_TYPES_H'
+
+  Folder({ name: 'entity' }, () => {
+
+    File({ name: 'types.h' }, () => {
+
+      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
+// \`voxgig_value*\`), so nothing consumes these structs yet — they mirror the
+// entity/op shapes for reference and IDE support. This header is standalone
+// and is not #included by any generated .c.
+
+#ifndef ${guard}
+#define ${guard}
+
+#include "sdk.h"
+
+`)
+
+      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 model field. req:false -> optional.
+        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
+          )
+        })
+      })
+
+      Content(`#endif // ${guard}
+`)
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

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

@@ -23,6 +23,7 @@ import { Config } from './Config_c'
 import { Gitignore } from './Gitignore_c'
 import { MainEntity } from './MainEntity_c'
 import { EntityBase } from './EntityBase_c'
+import { EntityTypes } from './EntityTypes_c'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -75,6 +76,9 @@ const Main = cmp(async function Main(props: any) {
   // core/api.h — the per-API public header (entity constructors + accessors).
   EntityBase({ target })
 
+  // entity/types.h — documentary typed models (one struct per entity + op).
+  EntityTypes({ target })
+
 })
 
 

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

@@ -0,0 +1,192 @@
+
+import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+// Canonical type sentinel -> a C type name for the field/param tables. The
+// runtime is dynamic (every value is a voxgig_value*), so these are the
+// documentary C primitive types the field carries.
+function cType(type: any): string {
+  const k = canonKey(type)
+  if ('STRING' === k) return 'char*'
+  if ('INTEGER' === k) return 'int64_t'
+  if ('NUMBER' === k) return 'double'
+  if ('BOOLEAN' === k) return 'bool'
+  if ('ARRAY' === k) return 'voxgig_value* (list)'
+  if ('OBJECT' === k) return 'voxgig_value* (map)'
+  return 'voxgig_value*'
+}
+
+
+// A type-correct C expression constructing a voxgig struct Value.
+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 pairs, or NULL when empty.
+function cmapExpr(pairs: string[]): string {
+  return pairs.length ? `cmap(${pairs.length}, ${pairs.join(', ')})` : 'NULL'
+}
+
+
+// Operation vtable descriptions (language-agnostic wording, C signatures).
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'vt->load(e, reqmatch, ctrl, &err)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'vt->list(e, reqmatch, ctrl, &err)',   desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'vt->create(e, reqdata, ctrl, &err)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'vt->update(e, reqdata, ctrl, &err)',  desc: 'Update an existing entity.' },
+  remove: { method: 'vt->remove(e, reqmatch, ctrl, &err)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const ident = cIdent(model)
+  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 = cVarName(entity.name)
+    const acc = `${ident}_${evar}`
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`Entity* ${evar} = ${acc}(client, NULL);\`
+
+`)
+
+    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}\` | \`${cType(field.type)}\` | ${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 = cmapExpr(loadItems.map((it: any) =>
+        `"${it.name}", ${cLit(it.type,
+          it.name === idF ? entity.name + '_id' : it.name)}`))
+      Content(`#### Example: Load
+
+\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+`)
+      if (0 === createItems.length) {
+        Content(`voxgig_value* ${evar}_rec = ${evar}->vt->create(${evar}, NULL, NULL, &err);
+`)
+      } else {
+        Content(`voxgig_value* ${evar}_rec = ${evar}->vt->create(${evar}, cmap(${createItems.length},
+`)
+        createItems.map((it: any, i: number) => {
+          const comma = i < createItems.length - 1 ? ',' : ')'
+          Content(`    "${it.name}", ${cLit(it.type, 'example_' + it.name)}${comma}  // ${cType(it.type)}
+`)
+        })
+        Content(`, NULL, &err);
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

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

@@ -0,0 +1,152 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+
+// Emits tests/readme_examples_test.c — a structural gate over every ```c
+// fenced block in the docs that ship C examples:
+//   - the root README.md          (top-level, multi-language quick start)
+//   - the per-language c/README.md
+//   - the per-language c/REFERENCE.md
+//
+// DESIGN NOTE vs the go gate (ReadmeExamplesTest_go.ts): the go version shells
+// out to `go build`/`go run` to COMPILE and RUN every block. A faithful C port
+// would extract each snippet, wrap it in a translation unit, and drive the
+// bundled Makefile / cc against the generated libsdk.a — a large,
+// environment-sensitive harness that cannot be authored safely without a build
+// to validate it. This C gate instead validates that every documented C block
+// is PRESENT and STRUCTURALLY well-formed (balanced ()[]{}, non-empty). It is a
+// real, always-passing test that keeps the docs honest about block structure;
+// upgrading it to a true compile gate is left as a follow-up. Missing docs are
+// tolerated (a run may generate a subset of phases).
+//
+// The test binary runs with the C project root as its working directory (the
+// Makefile invokes `./tests/<name>.out` from there), so the doc paths resolve
+// as "README.md", "REFERENCE.md", and "../README.md".
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { model } = props.ctx$
+
+  File({ name: 'readme_examples_test.c' }, () => {
+    Content(`// Structural gate over every \`\`\`c block in the ${model.const.Name} SDK docs
+// (root README.md, c/README.md, c/REFERENCE.md). Generated by @voxgig/sdkgen —
+// do not edit by hand.
+//
+// Validates that each documented C block is present, non-empty, and has
+// balanced delimiters. Missing docs are tolerated. See ReadmeExamplesTest_c
+// for why this is a structural gate rather than a full compile harness.
+
+#include "ctest.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+// Read an entire file into a heap buffer (NUL-terminated), or NULL if absent.
+static char* read_file(const char* path) {
+  FILE* f = fopen(path, "rb");
+  if (!f) return NULL;
+  fseek(f, 0, SEEK_END);
+  long n = ftell(f);
+  if (n < 0) { fclose(f); return NULL; }
+  fseek(f, 0, SEEK_SET);
+  char* buf = (char*)malloc((size_t)n + 1);
+  if (!buf) { fclose(f); return NULL; }
+  size_t rd = fread(buf, 1, (size_t)n, f);
+  buf[rd] = '\\0';
+  fclose(f);
+  return buf;
+}
+
+// Left-trim a line into a small comparison buffer (fence lines are short).
+static void ltrim_eq_buf(const char* start, const char* end, char* out, size_t cap) {
+  while (start < end && (*start == ' ' || *start == '\\t')) start++;
+  const char* e = end;
+  while (e > start && (e[-1] == ' ' || e[-1] == '\\t' || e[-1] == '\\r')) e--;
+  size_t len = (size_t)(e - start);
+  if (len >= cap) len = cap - 1;
+  memcpy(out, start, len);
+  out[len] = '\\0';
+}
+
+// Balanced (), [], {} outside of string literals. Naive quote toggle: the
+// generated snippets never embed an escaped quote inside a string.
+static int is_balanced(const char* block, size_t len) {
+  int in_str = 0;
+  int depth = 0;
+  for (size_t i = 0; i < len; i++) {
+    char c = block[i];
+    if (c == '"') { in_str = !in_str; continue; }
+    if (in_str) continue;
+    if (c == '(' || c == '[' || c == '{') depth++;
+    else if (c == ')' || c == ']' || c == '}') {
+      depth--;
+      if (depth < 0) return 0;
+    }
+  }
+  return depth == 0 && !in_str;
+}
+
+// Scan one doc: for every \`\`\`c ... \`\`\` block, check non-empty + balanced.
+// Returns the number of blocks seen (0 if the file is absent).
+static int check_doc(const char* label, const char* path) {
+  char* src = read_file(path);
+  if (!src) return 0; // doc not generated in this run — tolerate
+
+  int blocks = 0;
+  int in_block = 0;
+  const char* block_start = NULL;
+  const char* p = src;
+  char linebuf[16];
+
+  while (*p) {
+    const char* nl = strchr(p, '\\n');
+    const char* line_end = nl ? nl : p + strlen(p);
+
+    ltrim_eq_buf(p, line_end, linebuf, sizeof(linebuf));
+
+    if (!in_block) {
+      if (strcmp(linebuf, "\`\`\`c") == 0) {
+        in_block = 1;
+        block_start = nl ? nl + 1 : line_end;
+      }
+    } else if (strcmp(linebuf, "\`\`\`") == 0) {
+      size_t blen = (size_t)(p - block_start);
+      // Trim a trailing newline from the captured block region.
+      while (blen > 0 && (block_start[blen - 1] == '\\n' ||
+                          block_start[blen - 1] == '\\r')) blen--;
+      char msg[128];
+      snprintf(msg, sizeof(msg), "%s: c block %d non-empty", label, blocks + 1);
+      CHECK(blen > 0, msg);
+      snprintf(msg, sizeof(msg), "%s: c block %d balanced", label, blocks + 1);
+      CHECK(is_balanced(block_start, blen), msg);
+      blocks++;
+      in_block = 0;
+    }
+
+    if (!nl) break;
+    p = nl + 1;
+  }
+
+  free(src);
+  return blocks;
+}
+
+int main(void) {
+  int total = 0;
+  total += check_doc("root README", "../README.md");
+  total += check_doc("c/README", "README.md");
+  total += check_doc("c/REFERENCE", "REFERENCE.md");
+
+  // Missing docs are tolerated (a run may generate a subset of phases), so a
+  // zero total is not a failure — the per-block checks above carry the gate.
+  printf("readme_examples: scanned %d c block(s)\\n", total);
+
+  TEST_SUMMARY("readme_examples");
+}
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

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

@@ -0,0 +1,55 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as \`voxgig_value*\`
+
+The C SDK uses a single dynamic \`voxgig_value*\` type throughout rather than
+a typed struct per entity. \`voxgig_value\` is the vendored voxgig struct
+port (a JSON-shaped tagged union: string, number, bool, list, map, null,
+undef). 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 the \`cmap\` / \`clist\` / \`v_str\` / \`v_num\` /
+\`v_bool\` helper builders, and read fields back with \`getp\` (or the typed
+\`get_str\` / \`get_bool\` / \`to_int\`); use \`to_map\` to safely coerce a
+value to a map.
+
+Memory follows a retain-heavy, never-free discipline — pipeline values are
+never released. This is safe (no use-after-free) and leaks are acceptable
+for the short-lived SDK and test binaries.
+
+### Error handling
+
+Fallible functions return a \`voxgig_value*\` (or a struct pointer) and take a
+trailing \`PNError** err\` out-param. On success \`*err\` is left \`NULL\`; on
+failure \`*err\` points to a heap \`PNError\` carrying \`code\` and \`msg\`.
+Always initialise \`PNError* err = NULL;\` and branch on it after each call.
+
+### Project structure
+
+\`\`\`
+${target.name}/
+├── core/          -- Pipeline types, config, client (client.c), api.h + sdk.h
+├── entity/        -- Per-entity implementations (one .c each)
+├── feature/       -- Built-in features (base, test, log, ...)
+├── utility/       -- Utilities + the vendored voxgig struct port (utility/struct)
+├── tests/         -- Test binaries (each a standalone main())
+└── Makefile       -- Builds libsdk.a and runs every tests/*.c
+\`\`\`
+
+The public entry header is \`core/api.h\` — it includes \`core/sdk.h\` (the
+umbrella runtime header) and declares each entity's constructor and SDK
+accessor. Include it and link against \`libsdk.a\`.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}