@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/ocaml/ReadmeEntity_ocaml.ts

@@ -0,0 +1,180 @@
+
+import { cmp, each, Content, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+// A type-correct OCaml `value` literal for a field's canonical type. Strings
+// render the quoted placeholder.
+function ocamlLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
+  if ('BOOLEAN' === k) return '(Bool true)'
+  if ('ARRAY' === k) return '(empty_list ())'
+  if ('OBJECT' === k) return '(empty_map ())'
+  return `(Str "${placeholder}")`
+}
+
+
+// The logical OCaml type of a field's canonical type. The SDK carries every
+// field inside the dynamic `value` variant, so this documents the underlying
+// shape a caller reads out of the value.
+function ocamlType(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return 'int'
+  if ('NUMBER' === k) return 'float'
+  if ('BOOLEAN' === k) return 'bool'
+  if ('STRING' === k) return 'string'
+  if ('ARRAY' === k) return 'value list'
+  if ('OBJECT' === k) return 'value map'
+  return 'value'
+}
+
+
+// The op accessor spelling on the entity_obj record, plus a language-agnostic
+// description.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'e_load reqmatch ctrl',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'e_list reqmatch ctrl',   desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'e_create reqdata ctrl',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'e_update reqdata ctrl',  desc: 'Update an existing entity.' },
+  remove: { method: 'e_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 || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    const fn = ocamlVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`let ${fn} = Sdk_client.${fn} client 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}\` | \`${ocamlType(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
+        ? `jo [${loadItems.map((it: any) =>
+          `("${it.name}", ${ocamlLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)})`).join('; ')}]`
+        : 'Noval'
+      Content(`#### Example: Load
+
+\`\`\`ocaml
+let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`ocaml
+let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`ocaml
+let ${fn} = (Sdk_client.${fn} client Noval).e_create (jo [
+`)
+      createItems.map((it: any) => {
+        Content(`    ("${it.name}", ${ocamlLit(it.type, 'example_' + it.name)});  (* ${ocamlType(it.type)} *)
+`)
+      })
+      Content(`]) Noval
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

package/project/.sdk/src/cmp/ocaml/ReadmeExamplesTest_ocaml.ts

@@ -0,0 +1,126 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+
+// Emits test/readme_examples_test.ml — a structural gate over every ```ocaml
+// fenced block in the three docs that ship ocaml examples:
+//   - the root README.md (top-level, multi-language quick start)
+//   - the per-language ocaml/README.md
+//   - the per-language ocaml/REFERENCE.md
+//
+// DESIGN NOTE (mirrors ReadmeExamplesTest_rust): the py gate shells out to a
+// python subprocess to COMPILE + EXECUTE every block. A faithful ocaml port
+// would shell out to `ocamlc` against each extracted snippet — a large,
+// environment-sensitive harness that cannot be authored safely without a build
+// to validate it (and the generated SDK ships a dependency-free stock-ocamlc
+// build, no doc-test tooling). This gate instead validates that every
+// documented ocaml 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
+// project that `ocamlc`s each block against the generated SDK) is a follow-up.
+// Missing docs are tolerated (a run may generate a subset of phases).
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  File({ name: 'readme_examples_test.' + target.ext }, () => {
+    Content(`(* Structural gate over every \`\`\`ocaml block in the ${model.const.Name} SDK
+ * docs (root README.md, ocaml/README.md, ocaml/REFERENCE.md). Generated by
+ * @voxgig/sdkgen — do not edit by hand.
+ *
+ * Validates that each documented ocaml block is present, non-empty, and has
+ * balanced delimiters. Missing docs are tolerated. See ReadmeExamplesTest_ocaml
+ * for why this is a structural gate rather than a full compile harness. *)
+
+open Testutil
+
+let fence = "\`\`\`ocaml"
+let close_fence = "\`\`\`"
+
+let trim = String.trim
+
+(* Read a whole file, or None when it is absent (a doc not generated). *)
+let read_file (path : string) : string option =
+  try Some (In_channel.with_open_text path In_channel.input_all)
+  with Sys_error _ -> None
+
+let split_lines (s : string) : string list = String.split_on_char '\\n' s
+
+(* Extract the body of every \`\`\`ocaml ... \`\`\` fenced block from markdown.
+ * Returns (blocks, unclosed) where unclosed is true when a fence was opened
+ * but never closed before EOF — a malformed doc that must fail rather than
+ * silently drop the unterminated block. *)
+let extract_ocaml_blocks (md : string) : string list * bool =
+  let blocks = ref [] in
+  let cur = ref [] in
+  let in_block = ref false in
+  List.iter (fun line ->
+      let t = trim line in
+      if not !in_block then begin
+        if t = fence then begin in_block := true; cur := [] end
+      end
+      else if t = close_fence then begin
+        blocks := String.concat "\\n" (List.rev !cur) :: !blocks;
+        in_block := false
+      end
+      else cur := line :: !cur)
+    (split_lines md);
+  (List.rev !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. *)
+let is_balanced (block : string) : bool =
+  let in_str = ref false in
+  let stack = ref [] in
+  let ok = ref true in
+  String.iter (fun c ->
+      if !ok then
+        if c = '"' then in_str := not !in_str
+        else if not !in_str then
+          match c with
+          | '(' -> stack := ')' :: !stack
+          | '[' -> stack := ']' :: !stack
+          | '{' -> stack := '}' :: !stack
+          | ')' | ']' | '}' ->
+            (match !stack with
+             | top :: rest when top = c -> stack := rest
+             | _ -> ok := false)
+          | _ -> ())
+    block;
+  !ok && !stack = [] && not !in_str
+
+let docs = [
+  ("root README", "../README.md");
+  ("ocaml/README", "README.md");
+  ("ocaml/REFERENCE", "REFERENCE.md");
+]
+
+let () =
+  test "readme.ocaml_snippets_wellformed" (fun () ->
+      let total = ref 0 in
+      List.iter (fun (label, path) ->
+          match read_file path with
+          | None -> ()   (* doc not generated in this run — tolerate *)
+          | Some src ->
+            let (blocks, unclosed) = extract_ocaml_blocks src in
+            (* A fence opened but never closed is a malformed doc — fail
+             * rather than silently skipping the unterminated block. *)
+            check (label ^ " ocaml fence closed") (not unclosed);
+            List.iteri (fun i block ->
+                check (label ^ " block " ^ string_of_int (i + 1) ^ " non-empty")
+                  (trim block <> "");
+                check (label ^ " block " ^ string_of_int (i + 1) ^ " balanced delimiters")
+                  (is_balanced block);
+                incr total)
+              blocks)
+        docs;
+      check "at least one ocaml code block across the docs" (!total > 0))
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

package/project/.sdk/src/cmp/ocaml/ReadmeExplanation_ocaml.ts

@@ -0,0 +1,46 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as \`value\`
+
+The OCaml SDK uses a single dynamic \`value\` type throughout rather than a
+typed record per entity. \`value\` is the vendored voxgig struct port (a
+JSON-shaped variant: \`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.
+
+### Module structure
+
+\`\`\`
+${target.name}/
+├── sdk_client.ml               -- Main SDK client (constructors + accessors)
+├── sdk_config.ml               -- Embedded API config + feature factory
+├── sdk_error.ml                -- Branded error re-exports
+├── sdk_entity_*.ml             -- Per-entity implementations (one each)
+├── sdk_types.ml                -- Core pipeline types
+├── sdk_helpers.ml              -- jo / ja / getp and friends
+├── sdk_runtime.ml              -- Operation pipeline runner
+├── sdk_features.ml             -- Built-in features (base, test, log)
+├── utility/                    -- Vendored voxgig struct port
+└── test/                       -- Test suites
+\`\`\`
+
+The public surface lives in \`Sdk_client\` (the constructors and per-entity
+accessors); \`Sdk_helpers\` carries the \`jo\` / \`ja\` / \`getp\` value
+helpers. Open the runtime modules directly only when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

package/project/.sdk/src/cmp/ocaml/ReadmeHowto_ocaml.ts

@@ -0,0 +1,147 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+// A type-correct OCaml `value` literal for a field's canonical type.
+function ocamlLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
+  if ('BOOLEAN' === k) return '(Bool true)'
+  if ('ARRAY' === k) return '(empty_list ())'
+  if ('OBJECT' === k) return '(empty_map ())'
+  return '(Str "example")'
+}
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  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. primaryOp is null only when NO entity exposes
+  // any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const fn = exampleEntity ? ocamlVarName(exampleEntity.name) : 'entity'
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const field = primaryOp
+    ? ('load' === primaryOp ? 'e_load' :
+      'list' === primaryOp ? 'e_list' :
+        'create' === primaryOp ? 'e_create' :
+          'update' === primaryOp ? 'e_update' : 'e_remove')
+    : ''
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArg = 'Noval'
+  if (exampleEntity && 'list' === primaryOp) {
+    testArg = '(empty_map ())'
+  } else if (exampleEntity && isMatchOp) {
+    testArg = idF ? `(jo [("${idF}", Str "test01")])` : '(empty_map ())'
+  } 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 = `(jo [${chosen.map((it: any) => `("${it.name}", ${ocamlLit(it.type)})`).join('; ')}])`
+  }
+
+  // The op-driven test-mode line, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
+  const testModeExample = primaryOp
+    ? `(* Entity ops return the bare record and raise on error. *)
+  let ${fn} = (Sdk_client.${fn} client Noval).${field} ${testArg} Noval in
+  print_endline (stringify ${fn})  (* the mock response record *)`
+    : `let result = Sdk_client.direct client (jo [("path", Str "/api/resource"); ("method", Str "GET")]) in
+  print_endline (stringify result)`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`ocaml
+let result = Sdk_client.direct client (jo [
+    ("path", Str "/api/resource/{id}");
+    ("method", Str "GET");
+    ("params", jo [("id", Str "example")]);
+]) in
+(match getp result "ok" with
+ | Bool true ->
+   print_endline (stringify (getp result "status"));  (* 200 *)
+   print_endline (stringify (getp result "data"))      (* response body *)
+ | _ ->
+   (* A non-2xx response carries status + data (the error body); a transport
+      failure carries err instead. Read whichever is present. *)
+   print_endline (stringify (getp result "status"));
+   print_endline (stringify (getp result "err")))
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`ocaml
+(* prepare returns the fetch definition and raises on error. *)
+let fetchdef = Sdk_client.prepare client (jo [
+    ("path", Str "/api/resource/{id}");
+    ("method", Str "DELETE");
+    ("params", jo [("id", Str "example")]);
+]) in
+print_endline (stringify (getp fetchdef "url"));
+print_endline (stringify (getp fetchdef "method"));
+print_endline (stringify (getp fetchdef "headers"))
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`ocaml
+let () =
+  let client = Sdk_client.test () in
+  ${testModeExample}
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function:
+
+\`\`\`ocaml
+let mock_fetch = Func (fun _ _args _ _ ->
+    jo [("status", Num 200.); ("statusText", Str "OK"); ("headers", empty_map ());
+        ("json", json_thunk (jo [("id", Str "mock01")]))]) in
+let client = Sdk_client.make (jo [
+    ("base", Str "http://localhost:8080");
+    ("system", jo [("fetch", mock_fetch)]);
+]) in
+ignore client
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd ${target.name} && make test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

package/project/.sdk/src/cmp/ocaml/ReadmeInstall_ocaml.ts

@@ -0,0 +1,44 @@
+
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
+
+
+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 build from a source checkout — the SDK is dependency-free and compiles
+with the stock \`ocamlc\` (no opam packages, no dune):
+
+\`\`\`bash
+cd ${target.name} && make build
+\`\`\`
+
+`)
+    return
+  }
+
+  // Publish pending: not yet on the opam registry. Build from the git release
+  // tag or from a local source checkout. The generated library is
+  // dependency-free — a plain `make build` (stock `ocamlc`) is all it needs.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to the opam registry. Install it from the
+GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl}))
+or from a source checkout. The SDK is dependency-free and compiles with the
+stock \`ocamlc\` — no opam packages, no dune:
+
+\`\`\`bash
+cd ${target.name} && make build
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

package/project/.sdk/src/cmp/ocaml/ReadmeIntro_ocaml.ts

@@ -0,0 +1,68 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+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 OCaml conventions (a dependency-free library that compiles
+with the stock \`ocamlc\`).
+
+`)
+
+  // 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 \`Sdk_client.${ocamlVarName(exampleEntity.name)} client 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
+}