@voxgig/sdkgen 1.3.13 → 1.3.17

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

@@ -0,0 +1,152 @@
+
+
+// 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, names,
+  File, Content, Folder,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } 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 = 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)
+
+  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

@@ -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/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/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
+}

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

@@ -0,0 +1,132 @@
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+
+// Emits rust/tests/readme_examples_test.rs — a structural gate over every
+// ```rust fenced block in the three docs that ship rust examples:
+//   - the root README.md (top-level, multi-language quick start)
+//   - the per-language rust/README.md
+//   - the per-language rust/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 rust
+// port would shell out to `cargo`/`rustc` against extracted snippets — a large,
+// environment-sensitive harness that cannot be authored safely without a build
+// to validate it. This rust gate instead validates that every documented rust
+// block is PRESENT and STRUCTURALLY well-formed (balanced delimiters,
+// non-empty). It is a real, always-passing test that keeps the docs honest
+// about block structure; upgrading it to a true compile gate (a temp crate that
+// `cargo build`s each block against the generated SDK) is left as a follow-up.
+// Missing docs are tolerated (a run may generate a subset of phases).
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { ctx$: { model } } = props
+
+  File({ name: 'readme_examples_test.rs' }, () => {
+    Content(`// Structural gate over every \`\`\`rust block in the ${model.const.Name} SDK
+// docs (root README.md, rust/README.md, rust/REFERENCE.md). Generated by
+// @voxgig/sdkgen — do not edit by hand.
+//
+// Validates that each documented rust block is present, non-empty, and has
+// balanced delimiters. Missing docs are tolerated. See ReadmeExamplesTest_rust
+// for why this is a structural gate rather than a full compile harness.
+
+use std::fs;
+use std::path::PathBuf;
+
+// Extract the body of every \`\`\`rust ... \`\`\` fenced block from markdown.
+fn extract_rust_blocks(md: &str) -> Vec<String> {
+    let mut blocks: Vec<String> = Vec::new();
+    let mut in_block = false;
+    let mut cur: Vec<&str> = Vec::new();
+    for line in md.lines() {
+        let trimmed = line.trim();
+        if !in_block {
+            if trimmed == "\`\`\`rust" {
+                in_block = true;
+                cur = Vec::new();
+            }
+            continue;
+        }
+        if trimmed == "\`\`\`" {
+            blocks.push(cur.join("\\n"));
+            in_block = false;
+            continue;
+        }
+        cur.push(line);
+    }
+    blocks
+}
+
+// Balanced (), [], {} outside of string literals. Naive quote toggle: the
+// generated snippets never embed an escaped quote inside a string.
+fn is_balanced(block: &str) -> bool {
+    let mut in_str = false;
+    let mut depth: i32 = 0;
+    for c in block.chars() {
+        if c == '"' {
+            in_str = !in_str;
+            continue;
+        }
+        if in_str {
+            continue;
+        }
+        match c {
+            '(' | '[' | '{' => depth += 1,
+            ')' | ']' | '}' => {
+                depth -= 1;
+                if depth < 0 {
+                    return false;
+                }
+            }
+            _ => {}
+        }
+    }
+    depth == 0 && !in_str
+}
+
+#[test]
+fn readme_rust_snippets_wellformed() {
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let docs: [(&str, PathBuf); 3] = [
+        ("root README", manifest.join("..").join("README.md")),
+        ("rust/README", manifest.join("README.md")),
+        ("rust/REFERENCE", manifest.join("REFERENCE.md")),
+    ];
+
+    let mut total_blocks = 0usize;
+    for (label, path) in docs.iter() {
+        let src = match fs::read_to_string(path) {
+            Ok(s) => s,
+            Err(_) => continue, // doc not generated in this run — tolerate
+        };
+        let blocks = extract_rust_blocks(&src);
+        for (i, block) in blocks.iter().enumerate() {
+            assert!(
+                !block.trim().is_empty(),
+                "{}: rust block {} is empty",
+                label,
+                i + 1
+            );
+            assert!(
+                is_balanced(block),
+                "{}: rust block {} has unbalanced delimiters:\\n{}",
+                label,
+                i + 1,
+                block
+            );
+            total_blocks += 1;
+        }
+    }
+
+    assert!(
+        total_blocks > 0,
+        "no rust code blocks found in any README/REFERENCE doc"
+    );
+}
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

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

@@ -0,0 +1,44 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import { crateIdent } from './utility_rust'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+  const rustcrate = crateIdent(model)
+
+  Content(`### Data as \`Value\`
+
+The Rust SDK uses a single dynamic \`Value\` type throughout rather than a
+typed struct per entity. \`Value\` is the vendored voxgig struct port (a
+JSON-shaped enum: \`Str\`, \`Num\`, \`Bool\`, \`List\`, \`Map\`, \`Null\`,
+\`Noval\`). 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 \`jo\` / \`ja\` helpers and read fields back with
+\`getp\`; use \`to_map\` to safely coerce a value to a map.
+
+### Crate structure
+
+\`\`\`
+${target.name}/
+├── lib.rs                       -- Crate root (module decls + re-exports)
+├── core/                        -- Pipeline types, config, client (sdk.rs)
+├── entity/                      -- Per-entity clients (one module each)
+├── feature/                     -- Built-in features (base, test, log)
+└── utility/                     -- Utilities + the vendored voxgig struct port
+\`\`\`
+
+The public API is re-exported from the crate root, so \`use ${rustcrate}::{...}\`
+reaches the SDK client, \`Value\`, and the \`jo\` / \`ja\` / \`getp\` helpers
+directly. Import entity or utility modules only when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,142 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { crateIdent, rustVarName } from './utility_rust'
+
+
+// A type-correct rust expression constructing a voxgig struct Value.
+function rustLit(type: any): 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("example")'
+}
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const rustcrate = crateIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // Pick an entity with a real op (prefer a read op). 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'
+  const eVar = exampleEntity ? rustVarName(exampleEntity.name) : 'entity'
+  const method = exampleEntity ? rustVarName(exampleEntity.name) : 'entity'
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArg = 'Value::Noval'
+  if (exampleEntity && isMatchOp) {
+    testArg = idF ? `jo(vec![("${idF}", Value::str("test01"))])` : 'Value::Noval'
+  } else if (exampleEntity && ('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)
+    testArg = 0 < chosen.length
+      ? `jo(vec![${chosen.map((it: any) => `("${it.name}", ${rustLit(it.type)})`).join(', ')}])`
+      : 'Value::empty_map()'
+  }
+
+  // The op-driven test-mode line. A direct()-only SDK shows a direct() call.
+  const testModeExample = primaryOp
+    ? `// Entity ops return the bare record on Ok and Err on failure.
+let ${eVar} = client.${method}(Value::Noval).${primaryOp}(${testArg}, Value::Noval).unwrap();
+// ${eVar} contains the mock response record`
+    : `let result = client.direct(jo(vec![
+    ("path", Value::str("/api/resource")),
+    ("method", Value::str("GET")),
+])).unwrap();
+println!("{:?}", result);`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`rust
+let result = client.direct(jo(vec![
+    ("path", Value::str("/api/resource/{id}")),
+    ("method", Value::str("GET")),
+    ("params", jo(vec![("id", Value::str("example"))])),
+])).unwrap();
+
+if getp(&result, "ok") == Value::Bool(true) {
+    println!("{:?}", getp(&result, "status"));  // 200
+    println!("{:?}", getp(&result, "data"));    // response body
+} else {
+    // A non-2xx response carries status + data (the error body); a
+    // transport-level failure carries err instead. Only one is present.
+    println!("{:?} {:?}", getp(&result, "status"), getp(&result, "err"));
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`rust
+// prepare() returns the fetch definition on Ok and Err on failure.
+let fetchdef = client.prepare(jo(vec![
+    ("path", Value::str("/api/resource/{id}")),
+    ("method", Value::str("DELETE")),
+    ("params", jo(vec![("id", Value::str("example"))])),
+])).unwrap();
+
+println!("{:?}", getp(&fetchdef, "url"));
+println!("{:?}", getp(&fetchdef, "method"));
+println!("{:?}", getp(&fetchdef, "headers"));
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`rust
+let client = test_sdk(Value::Noval, Value::Noval);
+
+${testModeExample}
+\`\`\`
+
+### Point at a different server
+
+Override the base URL to reach a local or staging server:
+
+\`\`\`rust
+let client = ${model.const.Name}SDK::new(jo(vec![
+    ("base", Value::str("http://localhost:8080")),
+]));
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the crate root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd ${target.name} && cargo test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}