@voxgig/sdkgen 1.3.8 → 1.3.9

package/project/.sdk/tm/dart/test/utility.dart

@@ -0,0 +1,159 @@
+// Shared utility functions for unit tests.
+//
+// Provides the sdk-test-control.json loader (per-SDK skip control), the
+// env-override helper for live-mode configuration, and test data path
+// resolution. Port of the donor ts test/utility.ts.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'harness.dart' show T;
+
+// Resolve a path relative to the package root (CWD) or the test dir.
+String resolveTestPath(String rel) {
+  if (File(rel).existsSync()) {
+    return rel;
+  }
+  try {
+    final scriptDir = File(Platform.script.toFilePath()).parent.path;
+    final alt = scriptDir + '/../' + rel;
+    if (File(alt).existsSync()) {
+      return alt;
+    }
+    final alt2 = scriptDir + '/' + rel;
+    if (File(alt2).existsSync()) {
+      return alt2;
+    }
+  } catch (_e) {
+    // Fall through to the raw path.
+  }
+  return rel;
+}
+
+// Overrides configuration values with environment variables if available.
+Map<String, dynamic> envOverride(Map<String, dynamic> m) {
+  final env = Platform.environment;
+
+  if ('TRUE' == env['PROJECTNAME_TEST_LIVE'] ||
+      'TRUE' == env['PROJECTNAME_TEST_OVERRIDE']) {
+    for (final k in m.keys.toList()) {
+      var envval = env[k];
+      if (null != envval) {
+        envval = envval.trim();
+        m[k] = envval.startsWith('{') ? jsonDecode(envval) : envval;
+      }
+    }
+  }
+
+  m['PROJECTNAME_TEST_EXPLAIN'] =
+      env['PROJECTNAME_TEST_EXPLAIN'] ?? m['PROJECTNAME_TEST_EXPLAIN'];
+
+  return m;
+}
+
+// Loads sdk-test-control.json (cached). Returns an empty-skip object if
+// the file is missing or unparsable so tests never crash on a bad config.
+Map<String, dynamic>? _testControlCache;
+
+Map<String, dynamic> loadTestControl() {
+  if (null != _testControlCache) {
+    return _testControlCache!;
+  }
+  try {
+    final path = resolveTestPath('test/sdk-test-control.json');
+    _testControlCache = Map<String, dynamic>.from(
+        jsonDecode(File(path).readAsStringSync()));
+  } catch (_e) {
+    _testControlCache = {
+      'version': 1,
+      'test': {
+        'skip': {
+          'live': {'direct': [], 'entityOp': []},
+          'unit': {'direct': [], 'entityOp': []},
+        }
+      }
+    };
+  }
+  return _testControlCache!;
+}
+
+// Returns the skip decision for a given test name from sdk-test-control.json.
+// `kind` is 'direct' (matches by `test` field) or 'entityOp' (matches by
+// `entity` + `op`). `mode` is 'live' or 'unit'.
+Map<String, dynamic> isControlSkipped(String kind, String name, String mode) {
+  final ctrl = loadTestControl();
+  dynamic list = [];
+  final t = ctrl['test'];
+  if (t is Map) {
+    final skip = t['skip'];
+    if (skip is Map) {
+      final m = skip[mode];
+      if (m is Map) {
+        list = m[kind] ?? [];
+      }
+    }
+  }
+  for (final e in (list as List)) {
+    if (e is! Map) {
+      continue;
+    }
+    if ('direct' == kind && e['test'] == name) {
+      return {'skip': true, 'reason': e['reason']};
+    }
+    if ('entityOp' == kind) {
+      final key = (e['entity'] ?? '').toString() + '.' + (e['op'] ?? '').toString();
+      if (key == name) {
+        return {'skip': true, 'reason': e['reason']};
+      }
+    }
+  }
+  return {'skip': false};
+}
+
+// Skips the current test if sdk-test-control.json lists it. Returns true
+// when skipped (caller should `return` immediately).
+bool maybeSkipControl(T t, String kind, String name, bool live) {
+  final decision = isControlSkipped(kind, name, live ? 'live' : 'unit');
+  if (true == decision['skip']) {
+    t.skip((decision['reason'] ?? 'skipped via sdk-test-control.json').toString());
+    return true;
+  }
+  return false;
+}
+
+// Skips the current live test when required idmap keys aren't supplied.
+// Generated tests call this when they would otherwise pass null values
+// into a path/query param and 4xx the request.
+bool skipIfMissingIds(T t, Map setup, List<String> requiredKeys) {
+  if (true != setup['live']) {
+    return false;
+  }
+  final idmap = setup['idmap'];
+  final missing = requiredKeys
+      .where((k) => !(idmap is Map) || null == idmap[k])
+      .toList();
+  if (missing.isNotEmpty) {
+    t.skip('live test needs ' +
+        missing.join(', ') +
+        ' via *_ENTID env var (synthetic IDs only)');
+    return true;
+  }
+  return false;
+}
+
+// Per-test live pacing delay (ms). Read from sdk-test-control.json
+// `test.live.delayMs`; defaults to 500ms if absent or invalid.
+int liveDelayMs() {
+  final ctrl = loadTestControl();
+  final t = ctrl['test'];
+  final v = t is Map ? (t['live'] is Map ? t['live']['delayMs'] : null) : null;
+  return (v is num && v >= 0) ? v.toInt() : 500;
+}
+
+// Live pacing helper. Generated tests await this after live calls; it
+// sleeps liveDelayMs() only when the SDK's *_TEST_LIVE env var is set.
+Future<void> liveDelay(String liveEnvVar) async {
+  if ('TRUE' == Platform.environment[liveEnvVar]) {
+    await Future.delayed(Duration(milliseconds: liveDelayMs()));
+  }
+}

package/project/.sdk/tm/elixir/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 voxgig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/project/.sdk/tm/elixir/Makefile

@@ -0,0 +1,15 @@
+.PHONY: test build clean struct
+
+# Full ExUnit suite (includes the vendored struct corpus test).
+test:
+	mix test
+
+# Only the vendored struct corpus.
+struct:
+	mix test test/struct_corpus_test.exs
+
+build:
+	mix compile
+
+clean:
+	rm -rf _build

package/project/.sdk/tm/elixir/VERSION

@@ -0,0 +1 @@
+0.1.0

package/project/.sdk/tm/elixir/lib/projectname/context.ex

@@ -0,0 +1,138 @@
+# ProjectName SDK context
+#
+# The context is a reference-stable struct map node. Fields inherit from a
+# base context (the client root ctx, then the entity ctx) exactly like the
+# donor, so a feature hook that mutates ctx (or a nested spec/result/ctrl
+# node) is seen by every later stage.
+
+defmodule ProjectName.Context do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Helpers, as: H
+  alias ProjectName.{Control, Operation, Error}
+
+  def entity_name(entity) do
+    if S.ismap(entity) do
+      n = S.getprop(entity, "_name")
+      if n != nil, do: n, else: "_"
+    else
+      "_"
+    end
+  end
+
+  def make_error(ctx, code, msg), do: Error.new(code, msg, ctx)
+
+  def new(ctxmap \\ nil, basectx \\ nil) do
+    cm = if S.ismap(ctxmap), do: ctxmap, else: nil
+    gp = fn k -> H.get_ctx_prop(cm, k) end
+    bp = fn k -> if basectx != nil, do: S.getprop(basectx, k), else: nil end
+    inh = fn k -> v = gp.(k); if(v != nil, do: v, else: bp.(k)) end
+    inh_map = fn k -> v = H.to_map(gp.(k)); if(v != nil, do: v, else: bp.(k)) end
+
+    ctx = S.jm([])
+    S.setprop(ctx, "id", "C" <> Integer.to_string(:rand.uniform(89_999_999) + 10_000_000))
+    S.setprop(ctx, "out", S.jm([]))
+    S.setprop(ctx, "client", inh.("client"))
+    S.setprop(ctx, "utility", inh.("utility"))
+
+    # Ctrl.
+    ctrl_raw = gp.("ctrl")
+
+    cond do
+      S.ismap(ctrl_raw) ->
+        ctrl = Control.new(nil)
+        te = S.getprop(ctrl_raw, "throw_err")
+
+        if te != nil do
+          S.setprop(ctrl, "throw_err", te)
+        else
+          t = S.getprop(ctrl_raw, "throw")
+          if is_boolean(t), do: S.setprop(ctrl, "throw_err", t)
+        end
+
+        ex = S.getprop(ctrl_raw, "explain")
+        if S.ismap(ex), do: S.setprop(ctrl, "explain", ex)
+        ac = S.getprop(ctrl_raw, "actor")
+        if ac != nil, do: S.setprop(ctrl, "actor", ac)
+        pg = S.getprop(ctrl_raw, "paging")
+        if S.ismap(pg), do: S.setprop(ctrl, "paging", pg)
+        S.setprop(ctx, "ctrl", ctrl)
+
+      basectx != nil and bp.("ctrl") != nil ->
+        S.setprop(ctx, "ctrl", bp.("ctrl"))
+
+      true ->
+        S.setprop(ctx, "ctrl", Control.new(nil))
+    end
+
+    # Meta.
+    m = gp.("meta")
+    S.setprop(ctx, "meta", cond do
+      S.ismap(m) -> m
+      basectx != nil and bp.("meta") != nil -> bp.("meta")
+      true -> S.jm([])
+    end)
+
+    S.setprop(ctx, "config", inh_map.("config"))
+    S.setprop(ctx, "entopts", inh_map.("entopts"))
+    S.setprop(ctx, "options", inh_map.("options"))
+    S.setprop(ctx, "entity", inh.("entity"))
+    S.setprop(ctx, "shared", inh_map.("shared"))
+
+    opmap = inh_map.("opmap")
+    S.setprop(ctx, "opmap", if(opmap != nil, do: opmap, else: S.jm([])))
+
+    S.setprop(ctx, "data", H.or_(H.to_map(gp.("data")), S.jm([])))
+    S.setprop(ctx, "reqdata", H.or_(H.to_map(gp.("reqdata")), S.jm([])))
+    S.setprop(ctx, "match", H.or_(H.to_map(gp.("match")), S.jm([])))
+    S.setprop(ctx, "reqmatch", H.or_(H.to_map(gp.("reqmatch")), S.jm([])))
+
+    S.setprop(ctx, "point", inh.("point"))
+    S.setprop(ctx, "spec", inh.("spec"))
+    S.setprop(ctx, "result", inh.("result"))
+    S.setprop(ctx, "response", inh.("response"))
+
+    opname = H.or_(gp.("opname"), "")
+    S.setprop(ctx, "op", resolve_op(ctx, opname))
+
+    ctx
+  end
+
+  # Cache key is `<entity>:<opname>` so two entities sharing an op name get
+  # distinct cached Operations.
+  def resolve_op(ctx, opname) do
+    entname = entity_name(S.getprop(ctx, "entity"))
+    opmap = S.getprop(ctx, "opmap")
+    cache_key = entname <> ":" <> opname
+
+    cached = S.getprop(opmap, cache_key)
+
+    cond do
+      cached != nil ->
+        cached
+
+      opname == "" ->
+        Operation.new(nil)
+
+      true ->
+        config = S.getprop(ctx, "config")
+        opcfg = S.getpath(config, "entity." <> entname <> ".op." <> opname)
+        inpt = if opname == "update" or opname == "create", do: "data", else: "match"
+
+        points =
+          if S.ismap(opcfg) do
+            t = S.getprop(opcfg, "points")
+            if S.islist(t), do: t, else: S.jt([])
+          else
+            S.jt([])
+          end
+
+        op =
+          Operation.new(
+            S.jm(["entity", entname, "name", opname, "input", inpt, "points", points])
+          )
+
+        S.setprop(opmap, cache_key, op)
+        op
+    end
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/core.ex

@@ -0,0 +1,125 @@
+# ProjectName SDK core runtime objects.
+#
+# Control / Spec / Result / Response / Operation are all struct map nodes
+# (reference-stable, ETS-backed) built with small constructor modules so
+# the pipeline and feature hooks can read and mutate their fields uniformly
+# via struct getprop/setprop.
+
+defmodule ProjectName.Control do
+  alias Voxgig.Struct, as: S
+
+  # opts is a struct map node or nil.
+  def new(opts \\ nil) do
+    m = if S.ismap(opts), do: opts, else: S.jm([])
+
+    S.jm([
+      "throw_err", S.getprop(m, "throw_err"),
+      "err", nil,
+      "explain", S.getprop(m, "explain"),
+      "actor", S.getprop(m, "actor"),
+      "paging", S.getprop(m, "paging")
+    ])
+  end
+end
+
+defmodule ProjectName.Spec do
+  alias Voxgig.Struct, as: S
+
+  def new(specmap \\ nil) do
+    m = if S.ismap(specmap), do: specmap, else: S.jm([])
+    d = fn k, dflt -> v = S.getprop(m, k); if(v == nil, do: dflt, else: v) end
+
+    S.jm([
+      "parts", d.("parts", S.jt([])),
+      "headers", d.("headers", S.jm([])),
+      "alias", d.("alias", S.jm([])),
+      "base", d.("base", ""),
+      "prefix", d.("prefix", ""),
+      "suffix", d.("suffix", ""),
+      "params", d.("params", S.jm([])),
+      "query", d.("query", S.jm([])),
+      "step", d.("step", ""),
+      "method", d.("method", "GET"),
+      "body", S.getprop(m, "body"),
+      "url", d.("url", ""),
+      "path", d.("path", "")
+    ])
+  end
+end
+
+defmodule ProjectName.Result do
+  alias Voxgig.Struct, as: S
+
+  def new(resmap \\ nil) do
+    m = if S.ismap(resmap), do: resmap, else: S.jm([])
+
+    status =
+      case S.getprop(m, "status") do
+        s when is_integer(s) -> s
+        s when is_float(s) -> trunc(s)
+        _ -> -1
+      end
+
+    st = S.getprop(m, "statusText")
+    headers = S.getprop(m, "headers")
+    rm = S.getprop(m, "resmatch")
+
+    S.jm([
+      "ok", S.getprop(m, "ok") == true,
+      "status", status,
+      "status_text", if(is_binary(st), do: st, else: ""),
+      "headers", if(S.ismap(headers), do: headers, else: S.jm([])),
+      "body", S.getprop(m, "body"),
+      "err", S.getprop(m, "err"),
+      "resdata", S.getprop(m, "resdata"),
+      "resmatch", if(S.ismap(rm), do: rm, else: nil)
+    ])
+  end
+end
+
+defmodule ProjectName.Response do
+  alias Voxgig.Struct, as: S
+
+  def new(resmap \\ nil) do
+    m = if S.ismap(resmap), do: resmap, else: S.jm([])
+
+    status =
+      case S.getprop(m, "status") do
+        s when is_integer(s) -> s
+        s when is_float(s) -> trunc(s)
+        _ -> -1
+      end
+
+    st = S.getprop(m, "statusText")
+    jf = S.getprop(m, "json")
+
+    S.jm([
+      "status", status,
+      "status_text", if(is_binary(st), do: st, else: ""),
+      "headers", S.getprop(m, "headers"),
+      "json_func", if(S.isfunc(jf), do: jf, else: nil),
+      "body", S.getprop(m, "body"),
+      "err", S.getprop(m, "err")
+    ])
+  end
+end
+
+defmodule ProjectName.Operation do
+  alias Voxgig.Struct, as: S
+
+  defp strval(v, d), do: if(is_binary(v) and v != "", do: v, else: d)
+
+  def new(opmap \\ nil) do
+    m = if S.ismap(opmap), do: opmap, else: S.jm([])
+    raw = S.getprop(m, "points")
+    al = S.getprop(m, "alias")
+
+    S.jm([
+      "entity", strval(S.getprop(m, "entity"), "_"),
+      "name", strval(S.getprop(m, "name"), "_"),
+      "input", strval(S.getprop(m, "input"), "_"),
+      "points", if(S.islist(raw), do: raw, else: S.jt([])),
+      "alias", if(S.ismap(al), do: al, else: nil)
+    ])
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/entity_base.ex

@@ -0,0 +1,155 @@
+# ProjectName SDK generic entity behaviour
+#
+# Shared construction and data/match operations for every entity. The
+# per-entity modules add the op functions (load/list/...) and pass their own
+# module in so `make/1` can spawn a fresh instance. Construction and data
+# hooks are fired directly (no jostraca marker needed — these are fixed).
+
+defmodule ProjectName.EntityBase do
+  alias Voxgig.Struct, as: S
+  alias ProjectName.Helpers, as: H
+  alias ProjectName.{Context, Utility, Pipeline}
+
+  def construct(module, client, name, entopts \\ nil) do
+    entopts = if S.ismap(entopts), do: entopts, else: S.jm([])
+
+    if S.getprop(entopts, "active") == false do
+      :ok
+    else
+      S.setprop(entopts, "active", true)
+    end
+
+    ent = S.jm([])
+    S.setprop(ent, "_module", module)
+    S.setprop(ent, "_name", name)
+    S.setprop(ent, "_client", client)
+    S.setprop(ent, "_utility", ProjectName.get_utility(client))
+    S.setprop(ent, "_entopts", entopts)
+    S.setprop(ent, "_data", S.jm([]))
+    S.setprop(ent, "_match", S.jm([]))
+
+    entctx =
+      Context.new(S.jm(["entity", ent, "entopts", entopts]), ProjectName.get_root_ctx(client))
+
+    S.setprop(ent, "_entctx", entctx)
+
+    Utility.feature_hook(entctx, "PostConstructEntity")
+    ent
+  end
+
+  def get_name(ent), do: S.getprop(ent, "_name")
+
+  def make(ent) do
+    module = S.getprop(ent, "_module")
+    client = S.getprop(ent, "_client")
+    entopts0 = S.getprop(ent, "_entopts")
+    opts = S.jm([])
+    Enum.each(H.entries(entopts0), fn {k, v} -> S.setprop(opts, k, v) end)
+    apply(module, :new, [client, opts])
+  end
+
+  def data_set(ent, args) do
+    if args != nil do
+      S.setprop(ent, "_data", H.or_(H.to_map(S.clone(args)), S.jm([])))
+      Utility.feature_hook(S.getprop(ent, "_entctx"), "SetData")
+    end
+
+    ent
+  end
+
+  def data_get(ent) do
+    Utility.feature_hook(S.getprop(ent, "_entctx"), "GetData")
+    S.clone(S.getprop(ent, "_data"))
+  end
+
+  def match_set(ent, args) do
+    if args != nil do
+      S.setprop(ent, "_match", H.or_(H.to_map(S.clone(args)), S.jm([])))
+      Utility.feature_hook(S.getprop(ent, "_entctx"), "SetMatch")
+    end
+
+    ent
+  end
+
+  def match_get(ent) do
+    Utility.feature_hook(S.getprop(ent, "_entctx"), "GetMatch")
+    S.clone(S.getprop(ent, "_match"))
+  end
+
+  # Streaming operation. Runs `action` (an op name, e.g. "list") through the
+  # full pipeline and returns a lazy Elixir Stream of result items, so the
+  # `streaming` feature's incremental output is reachable (a normal op call
+  # materialises the whole result). When the streaming feature is active the
+  # result carries a `stream` closure and this yields from it (honouring
+  # chunkSize); otherwise it falls back to the materialised items, so stream
+  # always yields. Records are unwrapped to bare struct maps (matching list).
+  # `callopts` parameterises the call:
+  #   - ctrl:   per-call pipeline control (threaded onto the op ctx);
+  #   - body:   an enumerable/list payload for outbound (upload) streaming,
+  #             attached to the request (reqdata.body$ + a stream_out marker);
+  #   - signal: an optional 0-arity fn; when it returns true iteration stops.
+  def stream(ent, action, args \\ nil, callopts \\ nil) do
+    callopts = if S.ismap(callopts), do: callopts, else: S.jm([])
+    ctrl = H.or_(H.to_map(S.getprop(callopts, "ctrl")), S.jm([]))
+    S.setprop(ctrl, "stream", callopts)
+
+    ctxmap =
+      S.jm([
+        "opname", action,
+        "ctrl", ctrl,
+        "match", S.getprop(ent, "_match"),
+        "data", S.getprop(ent, "_data")
+      ])
+
+    am = H.to_map(args)
+    if am != nil, do: Enum.each(H.entries(am), fn {k, v} -> S.setprop(ctxmap, k, v) end)
+
+    ctx = Context.new(ctxmap, S.getprop(ent, "_entctx"))
+
+    # Outbound: expose an enumerable/list payload so the request builder /
+    # transport can stream it as the request body.
+    body = S.getprop(callopts, "body")
+
+    if body != nil do
+      reqdata = H.or_(H.to_map(S.getprop(ctx, "reqdata")), S.jm([]))
+      S.setprop(reqdata, "body$", body)
+      S.setprop(ctx, "reqdata", reqdata)
+      S.setprop(ctx, "stream_out", body)
+    end
+
+    Pipeline.run_op(ctx, fn -> nil end)
+
+    result = S.getprop(ctx, "result")
+    signal = S.getprop(callopts, "signal")
+    stream_fn = if result != nil, do: S.getprop(result, "stream"), else: nil
+
+    # Inbound: prefer the streaming feature's iterator; else fall back to the
+    # materialised items so stream always yields.
+    items =
+      if S.isfunc(stream_fn) do
+        stream_fn.()
+      else
+        rd = if result != nil, do: S.getprop(result, "resdata"), else: nil
+
+        cond do
+          S.islist(rd) -> Enum.map(0..(S.size(rd) - 1), fn i -> S.getelem(rd, i) end)
+          rd == nil -> []
+          true -> [rd]
+        end
+      end
+
+    items
+    |> Stream.take_while(fn _ -> not (S.isfunc(signal) and signal.() == true) end)
+    |> Stream.map(&stream_unwrap/1)
+  end
+
+  # Unwrap an entity node to its bare record; recurse into chunk lists.
+  defp stream_unwrap(item) do
+    cond do
+      S.ismap(item) and S.getprop(item, "_module") != nil -> data_get(item)
+      is_list(item) -> Enum.map(item, &stream_unwrap/1)
+      S.islist(item) -> Enum.map(0..(S.size(item) - 1), fn i -> stream_unwrap(S.getelem(item, i)) end)
+      true -> item
+    end
+  end
+end

package/project/.sdk/tm/elixir/lib/projectname/error.ex

@@ -0,0 +1,16 @@
+# ProjectName SDK error
+#
+# An exception struct so it can be `raise`d on the default (throw) path and
+# also stored as a plain value inside struct nodes (e.g. ctx.out["point"]
+# for the rbac short-circuit). `is_sdk_error` marks SDK-originated errors.
+
+defmodule ProjectName.Error do
+  defexception [:code, :msg, :sdk, :ctx, :result, :spec, is_sdk_error: true]
+
+  @impl true
+  def message(%__MODULE__{msg: msg}), do: msg || ""
+
+  def new(code \\ "", msg \\ "", ctx \\ nil) do
+    %__MODULE__{code: code, msg: msg, sdk: "ProjectName", ctx: ctx}
+  end
+end