@voxgig/sdkgen 3.4.5 → 3.4.7

package/project/.sdk/src/cmp/zig/fragment/Main.fragment.zig

@@ -22,7 +22,20 @@ const Spec = spec_mod.Spec;
 pub const ProjectNameSDK = struct {
     mode: []const u8 = "live",
     options: Value = .{ .null = {} },
-    utility: *Utility,
+    // NOT named `utility`, and NOT a name `zigVarName` can produce.
+    //
+    // Entity accessors are generated as methods on this same struct
+    // (MainEntity_zig), so an API with an entity called `utility` collided
+    // twice: Zig rejects a local binding that shadows the declaration, and
+    // `sdk.utility` resolves to the FIELD, which made the generated accessor
+    // unreachable.
+    //
+    // `zigVarName` lowercases every name it is given, so a field spelling with
+    // an uppercase letter is one no entity name can ever reach - which is why
+    // this is `sdkUtility` and not, say, `util_rt`, a name an entity called
+    // `util-rt` would map straight onto. The public reader is `get_utility()`,
+    // so this field is internal and free to be spelled this way.
+    sdkUtility: *Utility,
     features: std.ArrayList(Feature),
     rootctx: ?*Context = null,
 
@@ -31,22 +44,22 @@ pub const ProjectNameSDK = struct {
         sdk.* = .{
             .mode = "live",
             .options = h.vnull(),
-            .utility = Utility.new(),
+            .sdkUtility = Utility.new(),
             .features = std.ArrayList(Feature).init(h.A()),
             .rootctx = null,
         };
 
         const cfg = config.make_config();
 
-        const rootctx = sdk.utility.make_context(CtxSpec{
+        const rootctx = sdk.sdkUtility.make_context(CtxSpec{
             .client = sdk,
-            .utility = sdk.utility,
+            .utility = sdk.sdkUtility,
             .config = cfg,
             .options = options,
             .shared = h.omap(),
         }, null);
 
-        const opts = sdk.utility.make_options(rootctx);
+        const opts = sdk.sdkUtility.make_options(rootctx);
         sdk.options = opts;
 
         if (h.veq(h.getpath(&.{ "feature", "test", "active" }, opts), h.vbool(true))) {
@@ -71,7 +84,7 @@ pub const ProjectNameSDK = struct {
                 const fopts = h.getp(feature_opts, fname);
                 if (fopts == .object) {
                     if (h.get_bool(fopts, "active") orelse false) {
-                        sdk.utility.feature_add(rootctx, config.make_feature(fname));
+                        sdk.sdkUtility.feature_add(rootctx, config.make_feature(fname));
                     }
                 }
             }
@@ -80,9 +93,9 @@ pub const ProjectNameSDK = struct {
         // Initialize features.
         var snap = std.ArrayList(Feature).init(h.A());
         for (sdk.features.items) |f| snap.append(f) catch {};
-        for (snap.items) |f| sdk.utility.feature_init(rootctx, f);
+        for (snap.items) |f| sdk.sdkUtility.feature_init(rootctx, f);
 
-        sdk.utility.feature_hook(rootctx, "PostConstruct");
+        sdk.sdkUtility.feature_hook(rootctx, "PostConstruct");
 
         return sdk;
     }
@@ -92,7 +105,7 @@ pub const ProjectNameSDK = struct {
     }
 
     pub fn get_utility(self: *ProjectNameSDK) *Utility {
-        return Utility.copy(self.utility);
+        return Utility.copy(self.sdkUtility);
     }
 
     pub fn get_root_ctx(self: *ProjectNameSDK) *Context {
@@ -100,7 +113,6 @@ pub const ProjectNameSDK = struct {
     }
 
     pub fn prepare(self: *ProjectNameSDK, fetchargs_in: Value) E!Value {
-        const utility = self.utility;
 
         const fetchargs: Value = switch (fetchargs_in) {
             .object => fetchargs_in,
@@ -112,7 +124,7 @@ pub const ProjectNameSDK = struct {
             else => h.omap(),
         };
 
-        const ctx = utility.make_context(CtxSpec{
+        const ctx = self.sdkUtility.make_context(CtxSpec{
             .opname = "prepare",
             .ctrl = ctrl,
         }, self.get_root_ctx());
@@ -134,7 +146,7 @@ pub const ProjectNameSDK = struct {
             else => h.omap(),
         };
 
-        const headers = utility.prepare_headers(ctx);
+        const headers = self.sdkUtility.prepare_headers(ctx);
 
         const specmap = h.jo(&.{
             .{ "base", h.getp(options, "base") },
@@ -158,9 +170,9 @@ pub const ProjectNameSDK = struct {
             while (it.next()) |kv| h.setp(spec.headers, kv.key_ptr.*, kv.value_ptr.*);
         }
 
-        _ = try utility.prepare_auth(ctx);
+        _ = try self.sdkUtility.prepare_auth(ctx);
 
-        return utility.make_fetch_def(ctx);
+        return self.sdkUtility.make_fetch_def(ctx);
     }
 
     // Raw endpoint access is operator-controllable, like every entity op.
@@ -200,7 +212,6 @@ pub const ProjectNameSDK = struct {
     // a caller-supplied marker would let anyone opt straight back out of the
     // gate by passing it.
     fn raw_request(self: *ProjectNameSDK, fetchargs_in: Value) Value {
-        const utility = self.utility;
 
         const fetchdef = self.prepare(fetchargs_in) catch {
             return h.jo(&.{
@@ -218,13 +229,13 @@ pub const ProjectNameSDK = struct {
             else => h.omap(),
         };
 
-        const ctx = utility.make_context(CtxSpec{
+        const ctx = self.sdkUtility.make_context(CtxSpec{
             .opname = "direct",
             .ctrl = ctrl,
         }, self.get_root_ctx());
 
         const url = h.get_str(fetchdef, "url") orelse "";
-        const fetched = utility.fetch(ctx, url, fetchdef) catch {
+        const fetched = self.sdkUtility.fetch(ctx, url, fetchdef) catch {
             return h.jo(&.{
                 .{ "ok", h.vbool(false) },
                 .{ "err", h.vstr(if (ctx.pending_err) |e| e.msg else "fetch failed") },

package/project/.sdk/tm/zig/test/gotcha_test.zig

@@ -100,7 +100,7 @@ test "gotcha8: custom utility callable survives" {
     const fn_val = h.callable(@ptrCast(&probe_dummy), probeCall);
     const opts = h.jo(&.{.{ "utility", h.jo(&.{.{ "probe", fn_val }}) }});
     const client = sdk.SDK.new(opts);
-    const stored = h.getp(client.utility.custom, "probe");
+    const stored = h.getp(client.sdkUtility.custom, "probe");
     try testing.expect(stored == .function);
     const r = h.call_vfn(stored, h.vstr("x"));
     try testing.expect(r == .string and std.mem.eql(u8, r.string, "x"));
@@ -139,10 +139,10 @@ test "gotcha3: many features" {
 
 test "gotcha2: make_point surfaces out.point error" {
     const client = sdk.new();
-    const ctx = client.utility.make_context(.{ .opname = "list" }, client.get_root_ctx());
+    const ctx = client.sdkUtility.make_context(.{ .opname = "list" }, client.get_root_ctx());
     const e = ctx.make_error("rbac_denied", "denied");
     ctx.out_set("point", sdk.OutVal{ .err = e });
-    try testing.expectError(error.Sdk, client.utility.make_point(ctx));
+    try testing.expectError(error.Sdk, client.sdkUtility.make_point(ctx));
     try testing.expect(ctx.pending_err != null);
     try testing.expect(std.mem.eql(u8, ctx.pending_err.?.code, "rbac_denied"));
 }
@@ -152,8 +152,8 @@ test "gotcha2: make_point surfaces out.point error" {
 test "gotcha4: featureAdd before ordering" {
     const client = sdk.new();
     const ctx = client.get_root_ctx();
-    client.utility.feature_add(ctx, OrderFeat.make("aaa", vnull()));
-    client.utility.feature_add(ctx, OrderFeat.make("bbb", h.jo(&.{.{ "__before__", h.vstr("aaa") }})));
+    client.sdkUtility.feature_add(ctx, OrderFeat.make("aaa", vnull()));
+    client.sdkUtility.feature_add(ctx, OrderFeat.make("bbb", h.jo(&.{.{ "__before__", h.vstr("aaa") }})));
     var ai: usize = 999;
     var bi: usize = 999;
     for (client.features.items, 0..) |f, i| {
@@ -176,7 +176,7 @@ test "gotcha6: netsim offline error code" {
     });
     const client = sdk.SDK.new(opts);
     const ctx = client.get_root_ctx();
-    const r = client.utility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
+    const r = client.sdkUtility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
     try testing.expectError(error.Sdk, r);
     try testing.expect(std.mem.eql(u8, ctx.pending_err.?.code, "netsim_offline"));
 }
@@ -192,7 +192,7 @@ test "gotcha6: netsim conn error code" {
     });
     const client = sdk.SDK.new(opts);
     const ctx = client.get_root_ctx();
-    const r = client.utility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
+    const r = client.sdkUtility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }}));
     try testing.expectError(error.Sdk, r);
     try testing.expect(std.mem.eql(u8, ctx.pending_err.?.code, "netsim_conn"));
 }
@@ -215,7 +215,7 @@ test "gotcha6: netsim seeded latency is deterministic" {
             const ctx = client.get_root_ctx();
             var i: usize = 0;
             while (i < 4) : (i += 1) {
-                _ = client.utility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }})) catch {};
+                _ = client.sdkUtility.fetch(ctx, "http://x", h.jo(&.{.{ "url", h.vstr("http://x") }})) catch {};
             }
             return sleep_log.toOwnedSlice() catch &.{};
         }

package/src/cmp/ReadmeTop.ts

@@ -261,8 +261,13 @@ ${aboutMd.trim()}
         exCall = `const ${exLower} = await client.${ex}().load(${exLoadArg})`
       } else if ('create' === primaryOp || 'update' === primaryOp) {
         const exIdF = entityIdField(exEnt)
+        // Drop the id only when the request shape says it is OPTIONAL. It is
+        // server-assigned on a normal create, but an op whose id comes from a
+        // PATH PARAMETER requires it, and the typed CreateData then rejects a
+        // body without it. Same rule as dataArg in helpers/opExample.
         const shapeItems = opRequestShape(exEnt, primaryOp).items
-          .filter((it: any) => it.name !== exIdF && it.name !== 'id')
+          .filter((it: any) =>
+            (it.name !== exIdF && it.name !== 'id') || !it.optional)
         const required = shapeItems.filter((it: any) => !it.optional)
         // ALL required fields must appear or the literal is not assignable to
         // the typed CreateData/UpdateData; cap only the optional fallback.

package/src/helpers/opExample.ts

@@ -116,8 +116,18 @@ function matchArg(
 // `key: value` pairs (capped) in the target language's object syntax. Ensures
 // the body satisfies a typed CreateData/UpdateData (required fields present).
 function dataArg(lang: ExampleLang, ent: any, op: string, idF: string | null): string {
+  // The id is normally server-assigned on create, so it is dropped from the
+  // example body. But it is only safe to drop when the request shape says it is
+  // OPTIONAL: an op whose id comes from a PATH PARAMETER requires it, and a
+  // typed CreateData then rejects a body without it.
+  //
+  // Conecto's `/integrations/{slug}/actions/{action}/run/` is the case — the
+  // guide renames the `action` param to `id`, so ActionCreateData is
+  // `{id, slug, ok}` and the generated snippet emitted only `{slug, ok}`,
+  // failing to compile with "Property 'id' is missing".
   const items = opRequestShape(ent, op).items
-    .filter((it: any) => it.name !== idF && it.name !== 'id')
+    .filter((it: any) =>
+      (it.name !== idF && it.name !== 'id') || !it.optional)
   const required = items.filter((it: any) => !it.optional)
   // ALL required fields must appear (a typed CreateData rejects a partial); cap
   // only the optional fallback used when the op declares no required field.

package/src/sdkgen.ts

@@ -20,7 +20,8 @@ import type {
 } from './types'
 
 import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix,
-  CONFIG_DATA_THRESHOLD, CONFIG_REPR_VALUES, isConfigData, configRepr } from './utility'
+  CONFIG_DATA_THRESHOLD, CONFIG_REPR_VALUES, isConfigData, configRepr,
+  configReprSetting, configDefinition, clean, rawStringLiteral } from './utility'
 
 import { Main } from './cmp/Main'
 import { ExternalTarget } from './cmp/ExternalTarget'
@@ -781,6 +782,10 @@ export {
   CONFIG_REPR_VALUES,
   isConfigData,
   configRepr,
+  configReprSetting,
+  configDefinition,
+  clean,
+  rawStringLiteral,
 
   // Scaffold components need this to fail a generation with an actionable
   // message rather than a bare Error (py-data guards on its sibling `py`).

package/src/utility.ts

@@ -1,10 +1,12 @@
 
 import Path from 'node:path'
 
-import { JostracaResult } from 'jostraca'
+import { JostracaResult, each } from 'jostraca'
 
 import { KIT, getModelPath } from '@voxgig/apidef'
 
+import { serverVariables } from './helpers/serverVars'
+
 
 // Where a per-target component is loaded from: `<project>/.sdk/dist/<path>`.
 //
@@ -100,6 +102,10 @@ export {
   CONFIG_REPR_VALUES,
   isConfigData,
   configRepr,
+  configReprSetting,
+  configDefinition,
+  clean,
+  rawStringLiteral,
 }
 
 
@@ -166,3 +172,153 @@ function isConfigData(configJson: string, repr?: string): boolean {
 function configRepr(configJson: string, repr?: string): string {
   return isConfigData(configJson, repr) ? 'data' : 'literal'
 }
+
+
+// The per-SDK override, or 'auto'. `main.kit.config.repr` is optional, and
+// getModelPath throws rather than returning undefined for an absent path.
+function configReprSetting(model: any): string {
+  try {
+    return getModelPath(model, `main.${KIT}.config.repr`) || 'auto'
+  }
+  catch (_e) {
+    return 'auto'
+  }
+}
+
+
+// L0 NORMALISATION: strip what the emitted config must not carry.
+//
+// Three kinds of noise, and the distinction between them matters:
+//
+//   MODEL_META      jostraca's `each` injects index$/key$/val$ into every node
+//                   it iterates. Pure bookkeeping, and it leaked into every
+//                   generated SDK for years (5,231 occurrences in gitlab
+//                   alone) because this helper deleted keys during a walk that
+//                   assigned them straight back.
+//
+//   CONFIG_DEFAULT  a key whose value equals the default the reader already
+//                   applies. Emitting it is pure bulk. Only these three names
+//                   are dropped, and only at their default value - `entity$`
+//                   is real Seneca data, so no blanket suffix rule.
+//
+//   PAYLOAD_KEYS    the boundary. Under `default`/`example`/`examples` the
+//                   value is API DATA, not config, and an example that happens
+//                   to contain `active: true` must survive intact. Below one of
+//                   these keys default-dropping stops; metadata stripping does
+//                   not, because jostraca's bookkeeping is never payload.
+const MODEL_META = ['index$', 'key$', 'val$']
+
+const CONFIG_DEFAULT: Record<string, any> = {
+  active: true,
+  req: false,
+  reqd: false,
+}
+
+const PAYLOAD_KEYS = ['default', 'example', 'examples']
+
+function clean(o: any, dropDefaults?: boolean): any {
+  // Rebuild rather than delete in place: the caller's model is shared with
+  // every other component, and mutating it here would strip metadata a later
+  // target still needs.
+  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
+        // An ABSENT optional member, dropped rather than carried as undefined.
+        //
+        // Callers build `{fields, name, op, relations}` from an entity, and
+        // `op` and `relations` are optional - so the key exists with value
+        // undefined. JSON.stringify silently omits such a key, while the
+        // literal formatters emit it as None/nil/null, and the two
+        // representations would describe different configs for any entity
+        // without an `op`. Dropping it here fixes both branches at once,
+        // because both reach the emitter through this function.
+        if (undefined === node[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)
+}
+
+
+// The JSON as a source-level string literal, for a language whose SINGLE
+// quoted literal neither interpolates nor processes escapes beyond the quote
+// and the backslash - Ruby, PHP, Perl, Lua.
+//
+// Reproducing the JSON text VERBATIM is all that is needed, because the JSON
+// already encodes control characters and non-ASCII itself. That is why this is
+// preferred over the double-quoted form in those languages: Ruby and PHP
+// interpolate (`#{...}`, `$var`) and Lua does not understand `\uXXXX` at all,
+// so a double-quoted literal would need a language-specific escape table and
+// would get it wrong for exactly the inputs nobody tests.
+function rawStringLiteral(s: string): string {
+  return "'" + s.replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'"
+}
+
+
+// THE CANONICAL CONFIG OBJECT, and the JSON the threshold is measured on.
+//
+// Every target builds its config from this one function, so the literal a
+// target emits and the data that replaces it above the threshold cannot
+// describe different configs - which is the entire promise of rung L1. Before
+// this existed each target assembled its own, and they had already drifted:
+// `feature.<name>` came out as `{}` in Go and as nothing at all in ts when a
+// feature declared no config.
+//
+// Key order is `each`'s order, which is sorted, so the JSON is byte-stable
+// across runs exactly like the literal it replaces.
+function configDefinition(model: any): { def: any, json: string } {
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
+
+  const authActive = isAuthActive(model)
+  const authPrefix = resolveAuthPrefix(model)
+
+  let baseUrl = ''
+  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
+
+  const svars = serverVariables(model)
+
+  const entityDefs: any = {}
+  const entityStubs: any = {}
+  each(entity, (e: any) => {
+    entityDefs[e.name] = clean({
+      fields: e.fields,
+      name: e.name,
+      op: e.op,
+      relations: e.relations,
+    }, true)
+    entityStubs[e.name] = {}
+  })
+
+  const featureDefs: any = {}
+  each(feature, (f: any) => {
+    featureDefs[f.name] = f.config || {}
+  })
+
+  const options: any = { base: baseUrl }
+  if (0 < svars.length) {
+    options.server = svars.reduce((a: any, v: any) => (a[v.name] = v.dflt, a), {})
+  }
+  if (authActive) {
+    options.auth = { prefix: authPrefix }
+  }
+  options.headers = headers
+  options.entity = entityStubs
+
+  const def = {
+    main: { name: model.const.Name },
+    feature: featureDefs,
+    options,
+    entity: entityDefs,
+  }
+
+  return { def, json: JSON.stringify(def) }
+}