@voxgig/sdkgen 3.3.2 → 3.4.2

package/project/.sdk/src/cmp/swift/Config_swift.ts

@@ -61,7 +61,7 @@ const Config = cmp(async function Config(props: any) {
       name: ent.name,
       op: ent.op,
       relations: ent.relations,
-    })
+    }, true)
   })
 
   const options: any = {

package/project/.sdk/src/cmp/swift/utility_swift.ts

@@ -57,13 +57,64 @@ function swiftString(val: string): string {
 
 
 // Strip model-internal keys (ending in `$`) from a cloned value graph.
-function clean(o: any) {
-  return walk(clone(o), (k: any, v: any, p: any) => {
-    if (null != k && k.endsWith('$')) {
-      delete p[k]
+// Emission-time normalisation of a model subtree (L0).
+//
+// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
+// key$, val$). With `dropDefaults`, also drops keys whose value IS the
+// default the runtime already assumes when the key is absent, which is pure
+// payload — see CONFIG_DEFAULT.
+//
+// Rebuilds the tree rather than mutating during a walk. The previous
+// implementation walked a clone calling `delete p[k]`, but walk() assigns its
+// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
+// the delete was undone on the way out and the helper silently did nothing.
+// Returning `undefined` from the callback does not fix it either: setprop
+// stores undefined rather than removing the key, which then emits as a null.
+//
+// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
+// `active` means something different in feature config, where absent reads as
+// INACTIVE (see feature_init) — dropping `active: true` there would silently
+// disable the feature.
+// jostraca's iteration metadata, injected by each()/names() while it walks the
+// model. Listed explicitly rather than matched by trailing-dollar suffix: a
+// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
+// data -- so a blanket suffix match can silently drop a legitimate API field.
+const MODEL_META = ['index$', 'key$', 'val$']
+
+// Keys whose value IS the default the runtime already assumes when the key is
+// absent, so emitting them is pure payload.
+const CONFIG_DEFAULT: Record<string, any> = {
+  active: true,
+  req: false,
+  reqd: false,
+}
+
+// Subtrees carrying user payload rather than schema. An active:true inside an
+// OpenAPI example is DATA, not a default, so default-pruning stops at these
+// keys and everything below them is passed through untouched.
+const PAYLOAD_KEYS = ['default', 'example', 'examples']
+
+function clean(o: any, dropDefaults?: boolean): any {
+  const prune = (node: any, defaults: boolean): any => {
+    if (Array.isArray(node)) {
+      return node.map((n: any) => prune(n, defaults))
+    }
+    if (null != node && 'object' === typeof node) {
+      const out: any = {}
+      for (const k of Object.keys(node)) {
+        if (MODEL_META.includes(k)) {
+          continue
+        }
+        if (defaults && k in CONFIG_DEFAULT && CONFIG_DEFAULT[k] === node[k]) {
+          continue
+        }
+        out[k] = prune(node[k], defaults && !PAYLOAD_KEYS.includes(k))
+      }
+      return out
     }
-    return v
-  })
+    return node
+  }
+  return prune(o, true === dropDefaults)
 }
 
 

package/project/.sdk/src/cmp/ts/Config_ts.ts

@@ -104,7 +104,7 @@ const Config = cmp(async function Config(props: any) {
             name: n.name,
             op: n.op,
             relations: n.relations,
-          }), a), {}), { margin: 2 }).trim(),
+          }, true), a), {}), { margin: 2 }).trim(),
       }
     })
   })

package/project/.sdk/src/cmp/ts/utility_ts.ts

@@ -104,13 +104,64 @@ function formatJson(obj: any, flags?: { line?: boolean, margin?: number }): stri
 }
 
 
-function clean(o: any) {
-  return walk(clone(o), (k: any, v: any, p: any) => {
-    if (null != k && k.endsWith('$')) {
-      delete p[k]
+// Emission-time normalisation of a model subtree (L0).
+//
+// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
+// key$, val$). With `dropDefaults`, also drops keys whose value IS the
+// default the runtime already assumes when the key is absent, which is pure
+// payload — see CONFIG_DEFAULT.
+//
+// Rebuilds the tree rather than mutating during a walk. The previous
+// implementation walked a clone calling `delete p[k]`, but walk() assigns its
+// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
+// the delete was undone on the way out and the helper silently did nothing.
+// Returning `undefined` from the callback does not fix it either: setprop
+// stores undefined rather than removing the key, which then emits as a null.
+//
+// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
+// `active` means something different in feature config, where absent reads as
+// INACTIVE (see feature_init) — dropping `active: true` there would silently
+// disable the feature.
+// jostraca's iteration metadata, injected by each()/names() while it walks the
+// model. Listed explicitly rather than matched by trailing-dollar suffix: a
+// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
+// data -- so a blanket suffix match can silently drop a legitimate API field.
+const MODEL_META = ['index$', 'key$', 'val$']
+
+// Keys whose value IS the default the runtime already assumes when the key is
+// absent, so emitting them is pure payload.
+const CONFIG_DEFAULT: Record<string, any> = {
+  active: true,
+  req: false,
+  reqd: false,
+}
+
+// Subtrees carrying user payload rather than schema. An active:true inside an
+// OpenAPI example is DATA, not a default, so default-pruning stops at these
+// keys and everything below them is passed through untouched.
+const PAYLOAD_KEYS = ['default', 'example', 'examples']
+
+function clean(o: any, dropDefaults?: boolean): any {
+  const prune = (node: any, defaults: boolean): any => {
+    if (Array.isArray(node)) {
+      return node.map((n: any) => prune(n, defaults))
     }
-    return v
-  })
+    if (null != node && 'object' === typeof node) {
+      const out: any = {}
+      for (const k of Object.keys(node)) {
+        if (MODEL_META.includes(k)) {
+          continue
+        }
+        if (defaults && k in CONFIG_DEFAULT && CONFIG_DEFAULT[k] === node[k]) {
+          continue
+        }
+        out[k] = prune(node[k], defaults && !PAYLOAD_KEYS.includes(k))
+      }
+      return out
+    }
+    return node
+  }
+  return prune(o, true === dropDefaults)
 }
 
 

package/project/.sdk/src/cmp/zig/Config_zig.ts

@@ -67,7 +67,7 @@ const Config = cmp(async function Config(props: any) {
       name: n.name,
       op: n.op,
       relations: n.relations,
-    }), a), {})
+    }, true), a), {})
 
   const config = {
     main: { name: model.const.Name },

package/project/.sdk/src/cmp/zig/utility_zig.ts

@@ -77,13 +77,64 @@ function formatZigValue(val: any, indent: number = 0): string {
 
 
 // Deep-remove meta keys (`foo$`) from a model subtree (twin of go's clean).
-function clean(o: any) {
-  return walk(clone(o), (k: any, v: any, p: any) => {
-    if (null != k && k.endsWith('$')) {
-      delete p[k]
+// Emission-time normalisation of a model subtree (L0).
+//
+// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
+// key$, val$). With `dropDefaults`, also drops keys whose value IS the
+// default the runtime already assumes when the key is absent, which is pure
+// payload — see CONFIG_DEFAULT.
+//
+// Rebuilds the tree rather than mutating during a walk. The previous
+// implementation walked a clone calling `delete p[k]`, but walk() assigns its
+// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
+// the delete was undone on the way out and the helper silently did nothing.
+// Returning `undefined` from the callback does not fix it either: setprop
+// stores undefined rather than removing the key, which then emits as a null.
+//
+// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
+// `active` means something different in feature config, where absent reads as
+// INACTIVE (see feature_init) — dropping `active: true` there would silently
+// disable the feature.
+// jostraca's iteration metadata, injected by each()/names() while it walks the
+// model. Listed explicitly rather than matched by trailing-dollar suffix: a
+// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
+// data -- so a blanket suffix match can silently drop a legitimate API field.
+const MODEL_META = ['index$', 'key$', 'val$']
+
+// Keys whose value IS the default the runtime already assumes when the key is
+// absent, so emitting them is pure payload.
+const CONFIG_DEFAULT: Record<string, any> = {
+  active: true,
+  req: false,
+  reqd: false,
+}
+
+// Subtrees carrying user payload rather than schema. An active:true inside an
+// OpenAPI example is DATA, not a default, so default-pruning stops at these
+// keys and everything below them is passed through untouched.
+const PAYLOAD_KEYS = ['default', 'example', 'examples']
+
+function clean(o: any, dropDefaults?: boolean): any {
+  const prune = (node: any, defaults: boolean): any => {
+    if (Array.isArray(node)) {
+      return node.map((n: any) => prune(n, defaults))
+    }
+    if (null != node && 'object' === typeof node) {
+      const out: any = {}
+      for (const k of Object.keys(node)) {
+        if (MODEL_META.includes(k)) {
+          continue
+        }
+        if (defaults && k in CONFIG_DEFAULT && CONFIG_DEFAULT[k] === node[k]) {
+          continue
+        }
+        out[k] = prune(node[k], defaults && !PAYLOAD_KEYS.includes(k))
+      }
+      return out
     }
-    return v
-  })
+    return node
+  }
+  return prune(o, true === dropDefaults)
 }
 
 

package/project/.sdk/tm/c/core/point.c

@@ -40,7 +40,8 @@ Point* point_new(voxgig_value* altmap) {
   p->orig = dup_str(orig ? orig : "");
 
   p->select = to_map(getp(altmap, "select"));
-  bool active = false;
+  // Absent in config means ACTIVE: emission drops `active: true` as a default (sdkgen L0), so only an explicit `active: false` turns a point off.
+  bool active = true;
   get_bool(altmap, "active", &active);
   p->active = active;
   p->relations = getp(altmap, "relations");

package/project/.sdk/tm/csharp/core/Point.cs

@@ -13,7 +13,9 @@ public class Point
     public List<object?> Parts = new();
     public List<object?>? Params;
     public Dictionary<string, object?>? Select;
-    public bool Active;
+    // Absent in config means ACTIVE: emission drops `active: true` as a
+    // default (sdkgen L0), so only an explicit `active: false` turns a point off.
+    public bool Active = true;
     public List<object?>? Relations;
     public Dictionary<string, object?> Alias = new();
     public Dictionary<string, object?> Transform = new();

package/project/.sdk/tm/dart/lib/Point.dart

@@ -28,7 +28,8 @@ class Point {
     parts = vs.getprop(altmap, 'parts', []);
     params = vs.getprop(altmap, 'params', []);
     select = vs.getprop(altmap, 'select');
-    active = vs.getprop(altmap, 'active', false);
+    // Absent in config means ACTIVE: emission drops `active: true` as a default (sdkgen L0), so only an explicit `active: false` turns a point off.
+    active = vs.getprop(altmap, 'active', true);
     relations = vs.getprop(altmap, 'relations', []);
     alias = vs.getprop(altmap, 'alias', {});
     transform = vs.getprop(altmap, 'transform', {'req': null, 'res': null});

package/project/.sdk/tm/go/test/feature_harness_test.go

@@ -25,7 +25,7 @@ import (
 
 // fhHasFeature is true when this SDK was generated with the named feature.
 func fhHasFeature(name string) bool {
-	config := sdk.MakeConfig()
+	config := sdk.SharedConfig()
 	fm, _ := config["feature"].(map[string]any)
 	return fm != nil && fm[name] != nil
 }

package/project/.sdk/tm/go/utility/make_options.go

@@ -127,7 +127,11 @@ func makeOptionsUtil(ctx *core.Context) map[string]any {
 		sysFetch = sf
 	}
 
-	merged := vs.Merge([]any{map[string]any{}, cfgopts, opts})
+	// Clone the config side before merging: `config` is a process-wide
+	// singleton (see core.SharedConfig), and Merge would otherwise use its
+	// nested maps as merge TARGETS — one instance's options (server, headers,
+	// ...) would contaminate every instance constructed after it.
+	merged := vs.Merge([]any{map[string]any{}, vs.Clone(cfgopts), opts})
 	validated, _ := vs.Validate(merged, optspec)
 	opts = validated.(map[string]any)
 

package/project/.sdk/tm/java/core/Point.java

@@ -18,7 +18,9 @@ public class Point {
   public List<Object> parts = new ArrayList<>();
   public List<Object> params;
   public Map<String, Object> select;
-  public boolean active = false;
+  // Absent in config means ACTIVE: emission drops `active: true` as a
+  // default (sdkgen L0), so only an explicit `active: false` turns a point off.
+  public boolean active = true;
   public List<Object> relations;
   public Map<String, Object> alias = new LinkedHashMap<>();
   public Map<String, Object> transform = new LinkedHashMap<>();

package/project/.sdk/tm/js/src/Point.js

@@ -16,7 +16,9 @@ class Point {
     this.parts = getprop(altmap, 'parts', [])
     this.params = getprop(altmap, 'params', [])
     this.select = getprop(altmap, 'select')
-    this.active = getprop(altmap, 'active', false)
+    // Absent in config means ACTIVE: emission drops `active: true` as a default
+    // (sdkgen L0), so only an explicit `active: false` turns a point off.
+    this.active = getprop(altmap, 'active', true)
     this.relations = getprop(altmap, 'relations', [])
     this.alias = getprop(altmap, 'alias', {})
     this.transform = getprop(altmap, 'transform', { req: undefined, res: undefined })

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

@@ -13,7 +13,9 @@ class Point(pointmap: Map<String, Any?>?) {
   var parts: MutableList<Any?> = mutableListOf()
   var params: MutableList<Any?>? = null
   var select: MutableMap<String, Any?>? = null
-  var active: Boolean = false
+  // Absent in config means ACTIVE: emission drops `active: true` as a
+  // default (sdkgen L0), so only an explicit `active: false` turns a point off.
+  var active: Boolean = true
   var relations: MutableList<Any?>? = null
   var alias: MutableMap<String, Any?> = linkedMapOf()
   var transform: MutableMap<String, Any?> = linkedMapOf()

package/project/.sdk/tm/lua/utility/make_options.lua

@@ -104,7 +104,11 @@ local function make_options_util(ctx)
   -- Preserve system.fetch before merge/validate.
   local sys_fetch = vs.getpath(opts, "system.fetch")
 
-  local merged = vs.merge({ {}, cfgopts, opts })
+  -- Clone the config side before merging: `config` is a per-Lua-state
+  -- singleton (see config_shared), and merge would otherwise use its nested
+  -- tables as merge TARGETS — one instance's options (server, headers, ...)
+  -- would contaminate every instance constructed after it.
+  local merged = vs.merge({ {}, vs.clone(cfgopts), opts })
   local validated = vs.validate(merged, optspec)
   if type(validated) ~= "table" then
     validated = {}

package/project/.sdk/tm/php/test/FeatureTest.php

@@ -149,7 +149,7 @@ class FtHarness
     public static function hasFeature(string $name): bool
     {
         if (self::$feature_config === null) {
-            $config = ProjectNameConfig::make_config();
+            $config = ProjectNameConfig::shared_config();
             $f = $config['feature'] ?? [];
             self::$feature_config = is_array($f) ? $f : [];
         }

package/project/.sdk/tm/py/pkg/utility/make_options.py

@@ -96,7 +96,11 @@ def make_options_util(ctx):
     # Preserve system.fetch before merge/validate.
     sys_fetch = vs.getpath(opts, "system.fetch")
 
-    merged = vs.merge([{}, cfgopts, opts])
+    # Clone the config side before merging: `config` is a process-wide
+    # singleton (see config.shared_config), and merge would otherwise use its
+    # nested dicts as merge TARGETS — one instance's options (server, headers,
+    # ...) would contaminate every instance constructed after it.
+    merged = vs.merge([{}, vs.clone(cfgopts), opts])
     validated = vs.validate(merged, optspec)
     if not isinstance(validated, dict):
         validated = {}

package/project/.sdk/tm/py/test/feature_harness.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 
 from urllib.parse import quote
 
-from projectname_sdk.config import make_config
+from projectname_sdk.config import shared_config
 from projectname_sdk.features import _make_feature
 from projectname_sdk.core.control import ProjectNameControl
 from projectname_sdk.core.error import ProjectNameError
@@ -24,7 +24,7 @@ from projectname_sdk.core.spec import ProjectNameSpec
 
 # True when this SDK was generated with the named feature.
 def has_feature(name):
-    feature = make_config().get("feature")
+    feature = shared_config().get("feature")
     return isinstance(feature, dict) and feature.get(name) is not None
 
 

package/project/.sdk/tm/rb/test/feature_test.rb

@@ -15,7 +15,7 @@ require_relative "../ProjectName_sdk"
 module ProjectNameFeatureHarness
   # True when this SDK was generated with the named feature.
   def self.has_feature?(name)
-    f = ProjectNameConfig.make_config["feature"]
+    f = ProjectNameConfig.shared_config["feature"]
     f.is_a?(Hash) && !f[name].nil?
   end
 

package/project/.sdk/tm/rb/utility/make_options.rb

@@ -61,7 +61,11 @@ module ProjectNameUtilities
 
     sys_fetch = VoxgigStruct.getpath(opts, "system.fetch")
 
-    merged = VoxgigStruct.merge([{}, cfgopts, opts])
+    # Clone the config side before merging: `config` is a process-wide
+    # singleton (see Config.shared_config), and merge would otherwise use its
+    # nested hashes as merge TARGETS — one instance's options (server,
+    # headers, ...) would contaminate every instance constructed after it.
+    merged = VoxgigStruct.merge([{}, VoxgigStruct.clone(cfgopts), opts])
     validated = VoxgigStruct.validate(merged, optspec)
     opts = validated.is_a?(Hash) ? validated : {}
 

package/project/.sdk/tm/scala/core/Point.scala

@@ -13,7 +13,8 @@ class Point(pointmap: JMap[String, Object]) {
   var parts: JList[Object] = new ArrayList[Object]()
   var params: JList[Object] = null
   var select: JMap[String, Object] = null
-  var active: Boolean = false
+  // Absent in config means ACTIVE: emission drops `active: true` as a default (sdkgen L0), so only an explicit `active: false` turns a point off.
+  var active: Boolean = true
   var relations: JList[Object] = null
   var alias: JMap[String, Object] = new LinkedHashMap[String, Object]()
   var transform: JMap[String, Object] = new LinkedHashMap[String, Object]()

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/core/Point.swift

@@ -10,7 +10,9 @@ public final class Point {
   public var parts: VList = VList()
   public var params: VList? = nil
   public var select: VMap? = nil
-  public var active: Bool = false
+  // Absent in config means ACTIVE: emission drops `active: true` as a
+  // default (sdkgen L0), so only an explicit `active: false` turns a point off.
+  public var active: Bool = true
   public var relations: VList? = nil
   public var alias: VMap = VMap()
   public var transform: VMap = VMap()

package/project/.sdk/tm/ts/src/Point.ts

@@ -30,7 +30,9 @@ class Point {
     this.parts = getprop(altmap, 'parts', [])
     this.params = getprop(altmap, 'params', [])
     this.select = getprop(altmap, 'select')
-    this.active = getprop(altmap, 'active', false)
+    // Absent in config means ACTIVE: emission drops `active: true` as a default
+    // (sdkgen L0), so only an explicit `active: false` turns a point off.
+    this.active = getprop(altmap, 'active', true)
     this.relations = getprop(altmap, 'relations', [])
     this.alias = getprop(altmap, 'alias', {})
     this.transform = getprop(altmap, 'transform', { req: undefined, res: undefined })

package/project/.sdk/tm/zig/core/point.zig

@@ -12,7 +12,8 @@ pub const Point = struct {
     parts: Value,
     params: Value,
     select: Value,
-    active: bool = false,
+    // Absent in config means ACTIVE: emission drops `active: true` as a default (sdkgen L0), so only an explicit `active: false` turns a point off.
+    active: bool = true,
     relations: Value,
     alias: Value,
     transform: Value,

package/src/cmp/Readme.ts

@@ -9,6 +9,7 @@ import { ReadmeErrors } from './ReadmeErrors'
 import { ReadmeModel } from './ReadmeModel'
 import { ReadmeOptions } from './ReadmeOptions'
 import { ReadmeEntity } from './ReadmeEntity'
+import { ReadmeUnions } from './ReadmeUnions'
 import { ReadmeHowto } from './ReadmeHowto'
 import { ReadmeExplanation } from './ReadmeExplanation'
 import { ReadmeRef } from './ReadmeRef'
@@ -28,6 +29,7 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeModel({ target })
     ReadmeOptions({ target })
     ReadmeEntity({ target })
+    ReadmeUnions({ target })
     ReadmeExplanation({ target })
 
     Content(`

package/src/cmp/ReadmeUnions.ts

@@ -0,0 +1,90 @@
+import { cmp, each, Content } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+
+// Fields whose type could not be narrowed because the API definition describes
+// them with an UNTAGGED union: `oneOf`/`anyOf` branches carrying no
+// `discriminator`, so the specification never states which variant a given
+// value is. apidef records the widest such union it finds beneath each field
+// (see ModelField.union); this section reports them.
+//
+// Without this, those fields read as a modelling failure — a `groups` field
+// typed as a bare array looks like the generator gave up, when in fact the
+// definition offers nothing to narrow it to. Saying so is the difference
+// between an SDK that looks unfinished and one that documents the API it was
+// given.
+//
+// Two-branch unions are NOT reported: `oneOf: [string, number]` is a routine
+// either/or, an open type for it surprises nobody, and listing every one would
+// bury the cases that matter.
+const MIN_REPORTED_BRANCHES = 3
+
+
+const ReadmeUnions = cmp(function ReadmeUnions(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const rows: { entity: string, field: string, branches: number, depth: number }[] = []
+
+  each(entity, (ent: any) => {
+    if (false === ent.active) {
+      return
+    }
+    each(ent.fields, (field: any) => {
+      const union = field?.union
+      if (null == union || union.branches < MIN_REPORTED_BRANCHES) {
+        return
+      }
+      rows.push({
+        entity: ent.name,
+        field: field.name,
+        branches: union.branches,
+        depth: union.depth,
+      })
+    })
+  })
+
+  if (0 === rows.length) {
+    return
+  }
+
+  // Widest first: the worst offender is the one a reader needs to see.
+  rows.sort((a, b) => b.branches - a.branches || a.entity.localeCompare(b.entity) ||
+    a.field.localeCompare(b.field))
+
+  const plural = 1 === rows.length ? 'field is' : 'fields are'
+
+  Content(`
+## Open types
+
+${rows.length} ${plural} carried as open values rather than typed structures.
+This follows from the API definition, not from a gap in this SDK: the
+definition describes ${1 === rows.length ? 'it' : 'them'} with untagged unions —
+\`oneOf\`/\`anyOf\` branches with no \`discriminator\` — so it never states which
+variant a given value is. Nothing can select a branch reliably, so the SDK
+passes the value through unchanged rather than assert a shape the API does not
+guarantee.
+
+| Entity | Field | Variants | Nesting |
+| --- | --- | --- | --- |
+${rows.map((r) =>
+    `| \`${r.entity}\` | \`${r.field}\` | ${r.branches} | ` +
+    `${r.depth} ${1 === r.depth ? 'level' : 'levels'} |`).join('\n')}
+
+These values round-trip unchanged — read them, modify them, send them back. If
+the API adds a \`discriminator\` to the definition, regenerating will type them.
+Every other field is typed normally.
+`)
+})
+
+
+export {
+  ReadmeUnions,
+  MIN_REPORTED_BRANCHES,
+}