@voxgig/sdkgen 4.8.2 → 4.8.3

package/project/.sdk/tm/js/test/vendor/omni/util.js

@@ -0,0 +1,212 @@
+// VENDORED: @voxgig/omni 0.1.4 (javascript/src/util.js)
+// Source: https://github.com/voxgig/omni @ 8c3e1b573a8d35796f7fc45e3226b977023cabf7  [tag: sdk-20260904-1610-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// Omni internal JSON utilities.
+//
+// This module is deliberately self-contained: the omni runner must be able
+// to test *any* library, including libraries that provide these same
+// operations, so it can never borrow them from the system under test.
+// Zero third-party dependencies, by design.
+
+const NULLMARK = '__NULL__' // Value is JSON null.
+const UNDEFMARK = '__UNDEF__' // Value is not present (thus, undefined).
+const EXISTSMARK = '__EXISTS__' // Value exists (not undefined).
+
+// A map (JSON object)?
+function ismap(val) {
+  return null != val && 'object' === typeof val && !Array.isArray(val)
+}
+
+// A list (JSON array)?
+function islist(val) {
+  return Array.isArray(val)
+}
+
+// A container (map or list)?
+function isnode(val) {
+  return ismap(val) || islist(val)
+}
+
+// Deep copy a JSON value. Non-JSON values (functions, class instances) are
+// passed through by reference - the runner only ever clones test data.
+function clone(val) {
+  if (islist(val)) {
+    return val.map((entry) => clone(entry))
+  }
+
+  if (ismap(val)) {
+    const out = {}
+    for (const key of Object.keys(val)) {
+      out[key] = clone(val[key])
+    }
+    return out
+  }
+
+  return val
+}
+
+// Read a value from a nested structure by path. Returns undefined when any
+// step is missing.
+function getpath(val, path) {
+  let current = val
+
+  for (const part of path) {
+    if (islist(current)) {
+      const index = 'number' === typeof part ? part : parseInt(String(part), 10)
+      if (isNaN(index) || index < 0 || index >= current.length) {
+        return undefined
+      }
+      current = current[index]
+    } else if (ismap(current)) {
+      const key = String(part)
+      if (!Object.prototype.hasOwnProperty.call(current, key)) {
+        return undefined
+      }
+      current = current[key]
+    } else {
+      return undefined
+    }
+  }
+
+  return current
+}
+
+// Depth-first walk, applying `apply` to every node and leaf, children
+// first, then the containing node. `apply` may replace the value.
+function walk(val, apply, key, parent, path) {
+  const curpath = path || []
+
+  if (isnode(val)) {
+    if (islist(val)) {
+      for (let index = 0; index < val.length; index++) {
+        val[index] = walk(val[index], apply, index, val, [...curpath, index])
+      }
+    } else {
+      for (const childkey of Object.keys(val)) {
+        val[childkey] = walk(val[childkey], apply, childkey, val, [...curpath, childkey])
+      }
+    }
+  }
+
+  return apply(key, val, parent, curpath)
+}
+
+// Deep structural equality. Numbers compare by value, booleans never equal
+// numbers, map key order is not significant.
+function deepequal(a, b) {
+  if (a === b) {
+    return true
+  }
+
+  if (null == a || null == b) {
+    return (undefined === a && undefined === b) || (null === a && null === b)
+  }
+
+  const atype = typeof a
+  const btype = typeof b
+
+  if ('number' === atype && 'number' === btype) {
+    return a === b || (isNaN(a) && isNaN(b))
+  }
+
+  if (atype !== btype) {
+    return false
+  }
+
+  if (islist(a) && islist(b)) {
+    if (a.length !== b.length) {
+      return false
+    }
+    for (let index = 0; index < a.length; index++) {
+      if (!deepequal(a[index], b[index])) {
+        return false
+      }
+    }
+    return true
+  }
+
+  if (ismap(a) && ismap(b)) {
+    const akeys = Object.keys(a)
+    const bkeys = Object.keys(b)
+    if (akeys.length !== bkeys.length) {
+      return false
+    }
+    for (const key of akeys) {
+      if (!Object.prototype.hasOwnProperty.call(b, key)) {
+        return false
+      }
+      if (!deepequal(a[key], b[key])) {
+        return false
+      }
+    }
+    return true
+  }
+
+  return false
+}
+
+// Compact JSON text with map keys sorted, so that messages are identical
+// in every port regardless of local map ordering.
+function jsonstr(val) {
+  if (undefined === val) {
+    return 'undefined'
+  }
+
+  if (null === val) {
+    return 'null'
+  }
+
+  if ('string' === typeof val) {
+    return JSON.stringify(val)
+  }
+
+  if ('number' === typeof val) {
+    return Number.isFinite(val) ? String(val) : 'null'
+  }
+
+  if ('boolean' === typeof val) {
+    return val ? 'true' : 'false'
+  }
+
+  if (islist(val)) {
+    return '[' + val.map((entry) => jsonstr(entry)).join(',') + ']'
+  }
+
+  if (ismap(val)) {
+    const keys = Object.keys(val).sort()
+    return '{' + keys.map((key) => JSON.stringify(key) + ':' + jsonstr(val[key])).join(',') + '}'
+  }
+
+  if ('function' === typeof val) {
+    return '[Function' + (val.name ? ' ' + val.name : '') + ']'
+  }
+
+  return JSON.stringify(String(val))
+}
+
+// Human readable form of a value: strings verbatim, everything else as
+// compact JSON.
+function stringify(val) {
+  return 'string' === typeof val ? val : jsonstr(val)
+}
+
+// Render a path as a dotted string.
+function pathify(path) {
+  return (path || []).map((part) => String(part)).join('.')
+}
+
+module.exports = {
+  NULLMARK,
+  UNDEFMARK,
+  EXISTSMARK,
+  clone,
+  deepequal,
+  getpath,
+  islist,
+  ismap,
+  isnode,
+  jsonstr,
+  pathify,
+  stringify,
+  walk,
+}

package/project/.sdk/tm/kotlin/core/Utility.kt

@@ -33,7 +33,7 @@ class Utility private constructor(register: Boolean) {
   lateinit var prepareAuth: (Context) -> Spec
   lateinit var prepareBody: (Context) -> Any?
   lateinit var prepareHeaders: (Context) -> MutableMap<String, Any?>
-  lateinit var prepareMethod: (Context) -> String
+  lateinit var prepareMethod: (Context) -> String?
   lateinit var prepareParams: (Context) -> MutableMap<String, Any?>
   lateinit var preparePath: (Context) -> String
   lateinit var prepareQuery: (Context) -> MutableMap<String, Any?>

package/project/.sdk/tm/kotlin/test/OmniResolver.kt

@@ -0,0 +1,343 @@
+package KOTLINPACKAGE.sdktest
+
+// The corpus test runner: vendored @voxgig/omni driven through its NATIVE
+// API (voxgig.omni.makeRunner(spec, provider)), presented to the corpus
+// tests in the struct-runner shape they already use (run.spec, run.runset,
+// run.runsetflags, run.client). No compat shim is vendored: the adapter
+// below IS the whole bridge, per language, per the vendor-tag rollout
+// (docs/design/vendor-tag-rollout.md, Decision 4). It supersedes the
+// engine half of RunnerSupport (runset/matchDeep) and the whole
+// StructRunner class (support lives on in RunnerSupport).
+//
+// Kotlin-specific decisions, each load-bearing:
+//
+// 1. TWO VALUE MODELS. The vendored kotlin omni port has a sealed `Json`
+//    (Absent/Null/Bool/Num/Str/JList/JMap); the SDK runtime has plain
+//    `Any?` - LinkedHashMap, MutableList, String, Long/Double, Boolean,
+//    null, and Struct.UNDEF for "no value". `toStruct`/`toOmni` convert at
+//    the subject boundary. Integral numbers cross as Long, matching what
+//    the SDK's own Json parser feeds the utilities. Ported from the
+//    struct kotlin port's own omni bridge (voxgig/struct
+//    kotlin/src/test/kotlin/voxgig/struct/Omni.kt).
+//
+// 2. ZERO-ARGUMENT ENTRIES. The corpus carries entries with no `in`,
+//    `args` or `ctx`, meaning "call the subject with NO argument". The
+//    kotlin port already distinguishes that case natively - such an entry
+//    arrives as one `Json.Absent` argument - so no novalargs spec rewrite
+//    (go) and no compat shim (lua/php) is needed: `toStruct(Json.Absent)`
+//    IS `Struct.UNDEF`, the port's own no-value sentinel, and
+//    `toOmni(Struct.UNDEF)` is `Json.Absent` on the way out.
+//
+// 3. MUTATED ARGUMENTS CANNOT CROSS BY IDENTITY. `toStruct` builds new
+//    containers, so an in-place rewrite by the subject would be invisible
+//    to the runner - and `match: {args: ...}` asserts exactly that
+//    (minor/setpath, merge/integrity), as does every `match: {ctx: ...}`
+//    read of state a subject wrote back with `omniSyncCtx`. So the
+//    wrapped subject REFILLS omni's own (mutable) containers in place
+//    after the call (`writeback`), which the runner then matches against.
+//    Safe because the runner clones `entry.in` before handing it over.
+//
+// 4. CONTEXTS STAY MAPS ACROSS THE RUNNER. omni sets `entry.ctx` to
+//    args[0] and `match: {ctx: ...}` assertions read THROUGH it with
+//    omni's own getpath, which walks Json maps only. So the subjects
+//    receive the MAP, build the typed Context with
+//    OmniResolver.omniCtx(args[0], ...) at the call site, run the
+//    utility, and write the observable ctx state back into the same map
+//    with omniSyncCtx - which is what makes the live SDK reachable
+//    through ctx.client for the generated utilities (omni#56; the same
+//    idiom as the go and java resolvers). NOTE: this port's runner marks
+//    `ctx.client` with `Json.Bool(true)` - presence, not identity - so a
+//    DEF-built client can never be resolved back from the ctx map;
+//    sections that need a specially-optioned client construct it at the
+//    call site (makeSpec/prepareAuth), same as the retired engine did.
+//
+// 5. THE VENDORED KOTLIN PORT LACKS THE omni#54 RUNNER FIXES the
+//    TypeScript port has at this tag (voxgig/omni#64 landed them for
+//    js/go/py only): Util.jsonstr has no cycle guard, and the match base
+//    is rebuilt per check rather than guarded. Both only bite on CYCLIC
+//    values - and a `Json` value built by this resolver's `toOmni` from
+//    acyclic corpus data cannot be cyclic, because typed SDK state (a
+//    Context, a client) never enters the Json world (decision 4). The
+//    errify half (non-Error throwables) cannot arise: kotlin subjects
+//    fail by THROWING, and the errify hook below keeps the SDK error's
+//    code for `match: {err: {code: ...}}` assertions.
+
+import java.nio.file.Paths
+import java.util.LinkedHashMap
+import kotlin.math.abs
+import kotlin.math.floor
+
+import voxgig.omni.Flags
+import voxgig.omni.Json
+import voxgig.omni.Provider
+import voxgig.omni.RunPack
+import voxgig.omni.Subject as OmniSubject
+import voxgig.omni.errify as omniErrify
+import voxgig.omni.loadspec
+import voxgig.omni.makeRunner as makeOmniRunner
+
+import KOTLINPACKAGE.core.Context
+import KOTLINPACKAGE.core.Helpers
+import KOTLINPACKAGE.core.ProjectNameSDK
+import KOTLINPACKAGE.core.SdkError
+import KOTLINPACKAGE.core.Utility
+import KOTLINPACKAGE.utility.struct.Struct
+
+@Suppress("UNCHECKED_CAST")
+object OmniResolver {
+
+  // The sentinels, under the names the corpus tests already use.
+  const val NULLMARK = voxgig.omni.NULLMARK
+  const val UNDEFMARK = voxgig.omni.UNDEFMARK
+  const val EXISTSMARK = voxgig.omni.EXISTSMARK
+
+  /** The function under test, in this port's plain-value shape. */
+  fun interface Subject {
+    fun call(args: MutableList<Any?>): Any?
+  }
+
+  /** Resolves one named section of the spec. */
+  fun interface NamedRunner {
+    fun runner(name: String, store: Any?): Run
+  }
+
+  /**
+   * What the runner returns for one named spec section - the struct-runner
+   * shape the corpus call sites consume. A failing entry throws
+   * voxgig.omni.OmniError, which fails the JUnit test with the entry named.
+   */
+  class Run internal constructor(
+    private val pack: RunPack,
+    val client: ProjectNameSDK?,
+  ) {
+    /** The resolved spec section, in this port's plain-value shape. */
+    val spec: MutableMap<String, Any?> =
+      toStruct(pack.spec) as? MutableMap<String, Any?> ?: linkedMapOf()
+
+    /** A named group of the resolved spec. */
+    fun set(name: String): Any? = spec[name]
+
+    /** Run one set of test entries with omni's default flags. */
+    fun runset(testspec: Any?, subject: Subject?) {
+      runsetflags(testspec, Flags(), subject)
+    }
+
+    /** Run one set of test entries with explicit flags. */
+    fun runsetflags(testspec: Any?, flags: Flags, subject: Subject?) {
+      val wrapped: OmniSubject? = if (null == subject) {
+        null
+      } else {
+        { jargs ->
+          val pargs = jargs.mapTo(mutableListOf<Any?>()) { toStruct(it) }
+          val got = subject.call(pargs)
+          // Refill omni's own containers so `match.args` / `match.ctx`
+          // see in-place mutation (decision 3 above).
+          for (index in jargs.indices) {
+            writeback(jargs[index], pargs[index])
+          }
+          toOmni(got)
+        }
+      }
+      pack.runsetflags(toOmni(testspec), flags, wrapped)
+    }
+  }
+
+  /**
+   * The struct runner's makeRunner(testfile, client) signature, backed by
+   * vendored omni. `testfile` is a spec path (absolutized against the
+   * working directory - omni's docs say a port must resolve the path
+   * itself) or an already-parsed spec value (omni's own capability), which
+   * keeps smoke tests free of fixture files.
+   */
+  fun makeRunner(testfile: Any?, client: ProjectNameSDK?): NamedRunner {
+    val spec: Json = when (testfile) {
+      is Json -> testfile
+      is String -> loadspec(Paths.get(testfile).toAbsolutePath().normalize().toString())
+      else -> toOmni(testfile)
+    }
+
+    val runner = makeOmniRunner(spec, sdkProvider(client))
+
+    return NamedRunner { name, store ->
+      Run(runner.runner(name, if (null == store) Json.Absent else toOmni(store)), client)
+    }
+  }
+
+  /** omni's value model -> this port's (see decision 1 above). */
+  fun toStruct(value: Json): Any? = when (value) {
+    is Json.Absent -> Struct.UNDEF
+    is Json.Null -> null
+    is Json.Bool -> value.value
+    is Json.Num -> {
+      val d = value.value
+      // Integral JSON numbers become Long, exactly as the SDK's own
+      // zero-dep Json parser produces them - the utilities' arithmetic
+      // and string rendering are written against that contract.
+      if (d.isFinite() && floor(d) == d && abs(d) < 9007199254740992.0) d.toLong() else d
+    }
+    is Json.Str -> value.value
+    is Json.JList -> value.value.mapTo(mutableListOf()) { toStruct(it) }
+    is Json.JMap ->
+      LinkedHashMap<String, Any?>().also { out ->
+        value.value.forEach { (key, entry) -> out[key] = toStruct(entry) }
+      }
+  }
+
+  /**
+   * This port's value model -> omni's. A function or a sentinel has no
+   * JSON form and omni only ever stringifies one, so it becomes its own
+   * rendering rather than silently collapsing to null.
+   */
+  fun toOmni(value: Any?): Json = when {
+    value is Json -> value
+    value === Struct.UNDEF -> Json.Absent
+    null == value -> Json.Null
+    value is Boolean -> Json.Bool(value)
+    value is Number -> Json.Num(value.toDouble())
+    value is String -> Json.Str(value)
+    value is List<*> -> Json.JList(value.mapTo(mutableListOf()) { toOmni(it) })
+    value is Map<*, *> ->
+      Json.JMap(
+        LinkedHashMap<String, Json>().also { out ->
+          value.forEach { (key, entry) -> out["$key"] = toOmni(entry) }
+        },
+      )
+    else -> Json.Str(Struct.stringify(value))
+  }
+
+  /** Refill omni's own container from the (possibly rewritten) argument. */
+  private fun writeback(target: Json, source: Any?) {
+    if (target is Json.JMap && source is Map<*, *>) {
+      target.value.clear()
+      source.forEach { (key, entry) -> target.value["$key"] = toOmni(entry) }
+    } else if (target is Json.JList && source is List<*>) {
+      target.value.clear()
+      source.forEach { entry -> target.value.add(toOmni(entry)) }
+    }
+  }
+
+  /** Wrap a live client as an omni provider (see decision 4 above). */
+  private fun sdkProvider(client: ProjectNameSDK?): Provider = Provider(
+    // NO subject-by-name hook: the SDK's Utility fields are TYPED function
+    // properties (a Context in, a typed value out), so a generic name
+    // lookup cannot produce omni's (List<Json>) -> Json subject without a
+    // per-name adapter; every corpus call site passes its subject
+    // explicitly, so the hook would be dead weight (the java resolver's
+    // decision, unchanged here).
+    subject = null,
+
+    // A DEF.client entry becomes another live test SDK, wrapped the same
+    // way. (This port's runner cannot hand the provider back through the
+    // ctx map - see decision 4 - so a section needing that client also
+    // constructs it at the call site.)
+    client = { options ->
+      val opts = toStruct(options) as? MutableMap<String, Any?>
+      sdkProvider(ProjectNameSDK.testSDK(null, opts ?: linkedMapOf()))
+    },
+
+    contextify = null,
+
+    // Client options may reference the runner store.
+    inject = { options, store ->
+      val popts = toStruct(options)
+      Struct.inject(popts, toStruct(store))
+      toOmni(popts)
+    },
+
+    // Keep the SDK error's code beside its message, so a corpus
+    // `match: {err: {code: ...}}` can assert on it - the kotlin analogue
+    // of the omni#54 errify fix (see decision 5 above).
+    errify = { err ->
+      if (err is SdkError) {
+        val out = LinkedHashMap<String, Json>()
+        out["name"] = Json.str("SdkError")
+        out["message"] = Json.str(err.message)
+        if (err.code.isNotEmpty()) {
+          out["code"] = Json.str(err.code)
+        }
+        Json.JMap(out)
+      } else {
+        omniErrify(err)
+      }
+    },
+  )
+
+  /**
+   * Build the typed Context a generated utility takes from the ctx MAP
+   * omni handed the subject (args[0]). (The engine half of the retired
+   * RunnerSupport.runset call sites did this as makeCtxFromMap + fixctx,
+   * per section, by hand.)
+   */
+  fun omniCtx(arg: Any?, client: ProjectNameSDK?, utility: Utility?): Context {
+    val ctxmap = Helpers.toMapAny(arg) ?: linkedMapOf()
+    val ctx = RunnerSupport.makeCtxFromMap(ctxmap, client, utility)
+    RunnerSupport.fixctx(ctx, client)
+    return ctx
+  }
+
+  /**
+   * Write the OBSERVABLE state of a typed context back into the ctx map
+   * the entry holds, which is where a `match: {ctx: ...}` assertion reads
+   * (through the wrapped subject's writeback - decision 3). The subject
+   * mutated the typed context; the map is what the runner can walk. (The
+   * retired engine call sites did this per section, by hand, as "update
+   * entry ctx for match".)
+   */
+  fun omniSyncCtx(arg: Any?, ctx: Context?) {
+    val ctxmap = Helpers.toMapAny(arg)
+    if (null == ctxmap || null == ctx) {
+      return
+    }
+
+    val spec = ctx.spec
+    if (null != spec) {
+      val out = linkedMapOf<String, Any?>(
+        "base" to spec.base,
+        "prefix" to spec.prefix,
+        "suffix" to spec.suffix,
+        "path" to spec.path,
+        "method" to spec.method,
+        "params" to spec.params,
+        "query" to spec.query,
+        "headers" to spec.headers,
+        "step" to spec.step,
+        "alias" to spec.alias,
+      )
+      if (null != spec.body) {
+        out["body"] = spec.body
+      }
+      if (spec.url.isNotEmpty()) {
+        out["url"] = spec.url
+      }
+      ctxmap["spec"] = out
+    }
+
+    val result = ctx.result
+    if (null != result) {
+      val out = linkedMapOf<String, Any?>(
+        "ok" to result.ok,
+        "status" to result.status,
+        "statusText" to result.statusText,
+        "headers" to result.headers,
+      )
+      if (null != result.body) {
+        out["body"] = result.body
+      }
+      val err = result.err
+      if (null != err) {
+        out["err"] = linkedMapOf<String, Any?>("message" to err.message)
+      }
+      if (null != result.resdata) {
+        out["resdata"] = result.resdata
+      }
+      if (null != result.resmatch) {
+        out["resmatch"] = result.resmatch
+      }
+      ctxmap["result"] = out
+    }
+
+    if (null != ctx.response) {
+      ctxmap["response"] = "exists"
+    }
+  }
+}

package/project/.sdk/tm/kotlin/test/OmniSmokeTest.kt

@@ -0,0 +1,100 @@
+package KOTLINPACKAGE.sdktest
+
+// Smoke tests for the vendored omni runner itself: a runner that cannot
+// FAIL a bad entry would turn every corpus suite vacuously green, so pin
+// the failure paths, not just the happy one. (The kotlin peer of
+// tm/ts/test/omni.test.ts and tm/java/test/OmniSmokeTest.java.)
+
+import org.junit.jupiter.api.Assertions.assertNotNull
+import org.junit.jupiter.api.Assertions.assertThrows
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
+
+import voxgig.omni.OmniError
+
+import KOTLINPACKAGE.core.ProjectNameSDK
+
+class OmniSmokeTest {
+
+  // A minimal in-memory spec: no fixture file, no OMNI block (lenient v0,
+  // like the shared corpus).
+  private fun smokeSpec(): MutableMap<String, Any?> = linkedMapOf(
+    "primary" to linkedMapOf<String, Any?>(
+      "smoke" to linkedMapOf<String, Any?>(
+        "basic" to linkedMapOf<String, Any?>(
+          "set" to mutableListOf<Any?>(
+            linkedMapOf<String, Any?>("in" to 1, "out" to 2),
+            linkedMapOf<String, Any?>("in" to 41, "out" to 42),
+          ),
+        ),
+        "bad" to linkedMapOf<String, Any?>(
+          "set" to mutableListOf<Any?>(
+            linkedMapOf<String, Any?>("in" to 1, "out" to 999),
+          ),
+        ),
+        "err" to linkedMapOf<String, Any?>(
+          "set" to mutableListOf<Any?>(
+            linkedMapOf<String, Any?>("in" to 0, "err" to "zero refused"),
+          ),
+        ),
+      ),
+    ),
+  )
+
+  private val smokeInc = OmniResolver.Subject { args ->
+    val n = (args[0] as Number).toInt()
+    if (0 == n) {
+      throw RuntimeException("smoke: zero refused")
+    }
+    n + 1
+  }
+
+  private fun smokeRun(): OmniResolver.Run {
+    val runner = OmniResolver.makeRunner(smokeSpec(), ProjectNameSDK.testSDK())
+    val run = runner.runner("smoke", null)
+    assertNotNull(run.spec, "smoke spec section did not resolve")
+    return run
+  }
+
+  @Test
+  fun runsetPassesACorrectSubject() {
+    val run = smokeRun()
+    run.runset(run.spec["basic"], smokeInc)
+  }
+
+  @Test
+  fun runsetFailsAWrongResult() {
+    val run = smokeRun()
+
+    val err = assertThrows(
+      OmniError::class.java,
+      { run.runset(run.spec["bad"], smokeInc) },
+      "a wrong result went unreported - the corpus suites would be vacuously green",
+    )
+
+    assertTrue(
+      err.message.orEmpty().contains("result mismatch"),
+      "expected a result mismatch failure, got: ${err.message}",
+    )
+  }
+
+  @Test
+  fun expectedErrorIsMatchedAndAMissingOneFails() {
+    val run = smokeRun()
+
+    // The erroring subject satisfies the expected-error entry.
+    run.runset(run.spec["err"], smokeInc)
+
+    // A subject that does NOT raise must fail that same entry.
+    val err = assertThrows(
+      OmniError::class.java,
+      { run.runset(run.spec["err"], OmniResolver.Subject { args -> args[0] }) },
+      "a missing expected error went unreported",
+    )
+
+    assertTrue(
+      err.message.orEmpty().contains("expected error did not occur"),
+      "expected an expected-error failure, got: ${err.message}",
+    )
+  }
+}