@voxgig/sdkgen 1.3.14 → 1.3.18

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

@@ -0,0 +1,144 @@
+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.
+// Returns the blocks plus a flag that is true when the scan reached EOF with a
+// fence still open (an unterminated \`\`\`rust block) — the caller fails on it
+// rather than silently dropping the malformed block.
+fn extract_rust_blocks(md: &str) -> (Vec<String>, bool) {
+    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, in_block)
+}
+
+// Balanced (), [], {} outside of string literals, with each closer matching the
+// most-recent opener (so "([)]" is rejected, not just counted). 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 stack: Vec<char> = Vec::new();
+    for c in block.chars() {
+        if c == '"' {
+            in_str = !in_str;
+            continue;
+        }
+        if in_str {
+            continue;
+        }
+        match c {
+            '(' => stack.push(')'),
+            '[' => stack.push(']'),
+            '{' => stack.push('}'),
+            ')' | ']' | '}' => {
+                if stack.pop() != Some(c) {
+                    return false;
+                }
+            }
+            _ => {}
+        }
+    }
+    stack.is_empty() && !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, unterminated) = extract_rust_blocks(&src);
+        // A fence opened but never closed is a malformed doc — fail rather than
+        // silently skipping the unterminated block.
+        assert!(
+            !unterminated,
+            "{}: unterminated \`\`\`rust fence (block never closed)",
+            label
+        );
+        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
+}

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

@@ -0,0 +1,49 @@
+
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
+
+import { crateName } from './utility_rust'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  if (isPublished(model, target.name)) {
+    Content(`\`\`\`bash
+${installCommand(model, target.name)}
+\`\`\`
+
+Or add it as a path dependency in your \`Cargo.toml\`:
+
+\`\`\`toml
+[dependencies]
+${crateName(model)} = { path = "../${target.name}" }
+\`\`\`
+
+`)
+    return
+  }
+
+  // Publish pending: not yet on crates.io. Depend on the git release tag or
+  // on a local source checkout via a path dependency.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This crate is not yet published to crates.io. Depend on it from the GitHub
+release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or
+from a source checkout by adding it to your \`Cargo.toml\`:
+
+\`\`\`toml
+[dependencies]
+# From a source checkout:
+${crateName(model)} = { path = "../${target.name}" }
+
+# Or from the git release tag:
+# ${crateName(model)} = { git = "<repo-url>", tag = "${target.name}/vX.Y.Z" }
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

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

@@ -0,0 +1,66 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { rustVarName } from './utility_rust'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client following idiomatic Rust conventions.
+
+`)
+
+  // Emphasise the entity-oriented design: the SDK surfaces the API as
+  // capitalised, semantic Entities with a small, uniform verb set rather
+  // than raw URL paths and query strings. The example entity name is
+  // derived from the model, never hardcoded.
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {})
+    .find((e: any) => e.active !== false) as any
+  const example = exampleEntity
+    ? `for example \`client.${rustVarName(exampleEntity.name)}(Value::Noval)\` — each`
+    : 'each'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
+
+  Content(`The SDK exposes the API as capitalised, semantic **Entities** — ${example}
+carrying a small, uniform set of operations (${opList}) instead of raw URL
+paths and query strings. You work with named resources and verbs, which
+keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}

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

@@ -0,0 +1,153 @@
+
+import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { crateIdent, rustVarName } from './utility_rust'
+
+
+const ReadmeModel = cmp(function ReadmeModel(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const rustcrate = crateIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  // Model-driven op rows for the shared entity interface: emit a row only for
+  // operations at least one active entity actually exposes.
+  const opUnion = new Set<string>()
+  entityList.forEach((e: any) => Object.keys(e.op || {})
+    .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
+  const opRowDefs: Record<string, string> = {
+    load: '| `load` | `(reqmatch: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Load a single entity by match criteria. |',
+    list: '| `list` | `(reqmatch: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | List entities matching the criteria (Ok is a `Value::List`). |',
+    create: '| `create` | `(reqdata: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Create a new entity. |',
+    update: '| `update` | `(reqdata: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Update an existing entity. |',
+    remove: '| `remove` | `(reqmatch: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Remove an entity. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  const apikeyOptionRow = isAuthActive(model)
+    ? '| `apikey` | `string` | API key for authentication. |\n'
+    : ''
+
+  Content(`### ${model.const.Name}SDK
+
+\`\`\`rust
+use ${rustcrate}::{${model.const.Name}SDK, Value};
+
+let client = ${model.const.Name}SDK::new(options);
+\`\`\`
+
+Creates a new SDK client. \`options\` is a \`Value\` map (\`Value::Noval\` for
+none) carrying any of the following keys:
+
+| Option | Value type | Description |
+| --- | --- | --- |
+${apikeyOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
+| \`prefix\` | \`string\` | URL path prefix prepended to all requests. |
+| \`suffix\` | \`string\` | URL path suffix appended to all requests. |
+| \`feature\` | \`map\` | Feature activation flags. |
+| \`system\` | \`map\` | System overrides (e.g. a custom fetcher). |
+
+### test_sdk
+
+\`\`\`rust
+use ${rustcrate}::{test_sdk, Value};
+
+let client = test_sdk(testopts, sdkopts);
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be
+\`Value::Noval\`.
+
+### ${model.const.Name}SDK methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`options_map\` | \`() -> Value\` | Deep copy of the current SDK options. |
+| \`get_utility\` | \`() -> Rc<Utility>\` | Copy of the SDK utility object. |
+| \`prepare\` | \`(fetchargs: Value) -> Result<Value, ${model.const.Name}Error>\` | Build an HTTP request definition without sending. |
+| \`direct\` | \`(fetchargs: Value) -> Result<Value, ${model.const.Name}Error>\` | Build and send an HTTP request. \`Ok\` is a result map (branch on \`ok\`). |
+`)
+
+  each(entityList, (ent: any) => {
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${rustVarName(ent.name)}\` | \`(entopts: Value) -> Rc<${ent.Name}Entity>\` | Create ${article} ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface
+
+All entities share the same interface.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+${opRows}
+| \`data\` | \`(args: Option<&Value>) -> Value\` | Get entity data (pass \`Some(&map)\` to set). |
+| \`matchv\` | \`(args: Option<&Value>) -> Value\` | Get entity match criteria (pass \`Some(&map)\` to set). |
+| \`make\` | \`() -> Rc<dyn Entity>\` | Create a new instance with the same options. |
+| \`get_name\` | \`() -> String\` | Return the entity name. |
+
+### Result shape
+
+Entity operations return \`Result<Value, ${model.const.Name}Error>\` — the
+bare result data on \`Ok\` (a \`Value::Map\` for single-entity ops, a
+\`Value::List\` for \`list\`) and the branded error on \`Err\`.
+
+The \`direct()\` escape hatch resolves to \`Ok\` even on a non-2xx response —
+it returns a result \`Value::Map\` you branch on via \`getp(&result, "ok")\`:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`bool\` | \`true\` if the HTTP status is 2xx. |
+| \`status\` | \`number\` | HTTP status code. |
+| \`headers\` | \`map\` | Response headers. |
+| \`data\` | \`any\` | Parsed JSON response body. |
+
+On error, \`ok\` is \`false\` and \`err\` carries the error value.
+
+`)
+
+  // Entities summary
+  Content(`### Entities
+
+`)
+  each(entityList, (ent: any) => {
+    const fields = ent.fields || []
+    const opnames = Object.keys(ent.op || {})
+    const ops = ent.op || {}
+    const points = each(ops).map((op: any) =>
+      op.points ? each(op.points) : []
+    ).flat()
+    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+
+    Content(`#### ${ent.Name}
+
+| Field | Description |
+| --- | --- |
+`)
+    each(fields, (field: any) => {
+      Content(`| \`${field.name}\` | ${field.short || ''} |
+`)
+    })
+
+    Content(`
+Operations: ${opnames.map((n: string) => n.charAt(0).toUpperCase() + n.slice(1)).join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

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

@@ -0,0 +1,60 @@
+
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
+
+
+const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
+  if (0 === publishedOptions.length) {
+    return
+  }
+
+  Content(`
+
+## Options
+
+Pass an options map when creating a client instance:
+
+`)
+
+  Content(`\`\`\`rust
+let client = ${model.Name}SDK::new(jo(vec![
+`)
+
+  publishedOptions.map((option: any) => {
+    if ('apikey' === option.name) {
+      Content(`    ("${option.name}", Value::str(std::env::var("${envName(model)}_APIKEY").unwrap_or_default())),
+`)
+    }
+    else {
+      const val = option.kind === 'string' ? 'Value::str("...")' : 'Value::Noval'
+      Content(`    // ("${option.name}", ${val}),
+`)
+    }
+  })
+
+  Content(`]));
+\`\`\`
+
+`)
+
+  Content(`| Option | Type | Description |
+| --- | --- | --- |
+`)
+
+  publishedOptions.map((option: any) => {
+    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
+`)
+  })
+
+  Content(`
+`)
+})
+
+
+export {
+  ReadmeOptions
+}