@voxgig/sdkgen 3.4.3 → 3.4.6

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

@@ -3,9 +3,11 @@ import {
   Content,
   File,
   cmp,
+  configDefinition,
+  configReprSetting,
   each,
   isAuthActive,
-  resolveAuthPrefix,
+  isConfigData,
 } from '@voxgig/sdkgen'
 
 
@@ -17,7 +19,6 @@ import {
 
 
 import {
-  clean,
   formatZigValue,
 } from './utility_zig'
 
@@ -31,52 +32,57 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  const entity = getModelPath(model, `main.${KIT}.entity`)
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
-  const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
+  // The canonical config OBJECT and its JSON, from the shared helper. Both
+  // representations render from the same `def`, so they cannot describe
+  // different configs - and this target picks up `options.server` (the
+  // OpenAPI server-variable defaults), which the hand-rolled build here
+  // omitted entirely.
+  const { def: config, json: configJson } = configDefinition(model)
+  const asData = isConfigData(configJson, configReprSetting(model))
 
-  const authActive = isAuthActive(model)
-  const authPrefix = resolveAuthPrefix(model)
+  File({ name: 'config.' + target.ext }, () => {
 
-  let baseUrl = ''
-  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
+    // ABOVE THE THRESHOLD: emit the model as DATA.
+    //
+    // The literal is one nested expression that Zig's comptime evaluator has
+    // to walk in full at every build; a string constant is one token, and
+    // `json_parse` (std.json at the boundary, then fromStdJson) builds the
+    // same Value at runtime.
+    //
+    // The escaping is JSON.stringify's, which is valid Zig: it escapes every
+    // backslash, so the JSON's own `\uXXXX` reaches the file as `\\uXXXX` and
+    // no Zig escape sequence is ever formed from it.
+    if (asData) {
+      Content(`// Generated API configuration (mirrors go/rust core/config).
 
-  const featureConfig: any = {}
-  each(feature, (f: any) => {
-    featureConfig[f.name] = f.config || {}
-  })
+const std = @import("std");
+const h = @import("helpers.zig");
+const types = @import("types.zig");
+const jsonparse = @import("../utility/jsonparse.zig");
+const Value = h.Value;
+const Feature = types.Feature;
 
-  const entityOptions: any = {}
-  each(entity, (ent: any) => {
-    entityOptions[ent.name] = {}
-  })
+/// THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
+///
+/// Emitted only above a size threshold, or when \`main.kit.config.repr\` pins
+/// it: for a small model the literal is smaller and far easier to read when
+/// debugging.
+const CONFIG_DATA: []const u8 = ${JSON.stringify(configJson)};
 
-  const options: any = {
-    base: baseUrl,
-    headers,
-    entity: entityOptions,
-  }
-  if (authActive) {
-    options.auth = { prefix: authPrefix }
-  }
-
-  const entityConfig = Object.values(entity || {}).reduce((a: any, n: any) => (
-    a[n.name] = clean({
-      fields: n.fields,
-      name: n.name,
-      op: n.op,
-      relations: n.relations,
-    }, true), a), {})
-
-  const config = {
-    main: { name: model.const.Name },
-    feature: featureConfig,
-    options,
-    entity: entityConfig,
-  }
+pub fn make_config() Value {
+    // Unreachable on error: the constant is generated by a JSON serialiser and
+    // never edited by hand. Panicking beats returning an empty config, which
+    // would fail far from the cause.
+    return jsonparse.json_parse(CONFIG_DATA) catch
+        @panic("${model.const.Name}: embedded config is not valid JSON");
+}
 
-  File({ name: 'config.' + target.ext }, () => {
+pub fn make_feature(name: []const u8) Feature {
+`)
+    }
+    else {
 
     Content(`// Generated API configuration (mirrors go/rust core/config).
 
@@ -92,6 +98,7 @@ pub fn make_config() Value {
 
 pub fn make_feature(name: []const u8) Feature {
 `)
+    }
 
     // The factory must be able to instantiate any built-in feature by name,
     // not just the ones the current API model configures — a caller can enable

package/src/cmp/ReadmeTop.ts

@@ -577,7 +577,16 @@ The OpenAPI spec(s) this SDK was generated from are kept in the
 
 `)
     if (upstreamUrl) {
-      Content(`- Upstream API: [${upstreamUrl}](${upstreamUrl})
+      // A per-tenant server URL carries an OpenAPI server variable —
+      // `https://{instance}.dreamapply.com/api` — and is the right thing to
+      // SHOW, because it tells the reader the host is theirs to fill in. It is
+      // not a thing to LINK: the braces are not a resolvable address, so a
+      // markdown link renders as clickable and dead. Show it as code instead.
+      const templated = /[{}]/.test(upstreamUrl)
+      Content(templated
+        ? `- Upstream API: \`${upstreamUrl}\`
+`
+        : `- Upstream API: [${upstreamUrl}](${upstreamUrl})
 `)
     }
     if (docsUrl && docsUrl !== upstreamUrl) {

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

@@ -19,7 +19,9 @@ import type {
   ActionResult,
 } from './types'
 
-import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix } from './utility'
+import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix,
+  CONFIG_DATA_THRESHOLD, CONFIG_REPR_VALUES, isConfigData, configRepr,
+  configReprSetting, configDefinition, clean, rawStringLiteral } from './utility'
 
 import { Main } from './cmp/Main'
 import { ExternalTarget } from './cmp/ExternalTarget'
@@ -776,6 +778,14 @@ export {
   requirePath,
   isAuthActive,
   resolveAuthPrefix,
+  CONFIG_DATA_THRESHOLD,
+  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>`.
 //
@@ -96,4 +98,227 @@ export {
   isAuthActive,
   resolveAuthPrefix,
   SdkGenError,
+  CONFIG_DATA_THRESHOLD,
+  CONFIG_REPR_VALUES,
+  isConfigData,
+  configRepr,
+  configReprSetting,
+  configDefinition,
+  clean,
+  rawStringLiteral,
+}
+
+
+// CONFIG REPRESENTATION (design rung L1, threshold from design Q7).
+//
+// Above a size threshold the API model is emitted as DATA - a JSON string
+// constant parsed once - rather than as a composite literal. Below it the
+// literal stays, because for a small model the literal is smaller, simpler,
+// faster to load and far easier to debug, and a symbol table would be pure
+// complexity.
+//
+// The threshold is on the JSON, not the emitted source, because the emitted
+// source size varies by language while the model does not. It is measured in
+// UTF-8 BYTES rather than string length: `.length` counts UTF-16 code units,
+// so a CJK-heavy model would read as roughly a third of its real size and
+// stay on the expensive literal path well past the point where it hurts.
+//
+// Measured on the real gitlab model (923.5 KB of JSON), Go, cold cache,
+// recompiling only the config package:
+//
+//                       composite literal   JSON string constant
+//   compile+link wall        30.80 s              0.34 s     91x faster
+//   peak compiler RSS         2.49 GB             0.06 GB    39x less
+//   binary                    7.44 MB             3.51 MB    2.1x smaller
+//
+// The reader side is unchanged either way: make_config returns the same map,
+// so nothing downstream can tell which representation it got.
+const CONFIG_DATA_THRESHOLD = 256 * 1024
+
+
+// Should this model be emitted as data rather than as a literal?
+//
+// `repr` is the per-SDK override from `main.kit.config.repr`: 'auto' (the
+// default) decides by size, 'data' and 'literal' pin it. The override is what
+// lets a small fixture exercise the data path - by size alone no test model
+// comes near the threshold, so the branch every large SDK depends on would
+// never be generated, compiled or run in CI.
+const CONFIG_REPR_VALUES = ['auto', 'data', 'literal']
+
+function isConfigData(configJson: string, repr?: string): boolean {
+  // An unknown value is REJECTED, not ignored. The aontu declaration
+  // documents the closed set but does not enforce it here, and silently
+  // treating `repr: 'date'` as `auto` would quietly restore the compile cost
+  // this exists to remove - the failure mode being a slow build nobody
+  // connects to a typo.
+  if (null != repr && '' !== repr && !CONFIG_REPR_VALUES.includes(repr)) {
+    throw new SdkGenError(
+      'sdkgen: main.kit.config.repr must be one of ' +
+      CONFIG_REPR_VALUES.join(', ') + ' (got: ' + repr + ')', {})
+  }
+  if ('data' === repr) {
+    return true
+  }
+  if ('literal' === repr) {
+    return false
+  }
+  return CONFIG_DATA_THRESHOLD < Buffer.byteLength(configJson, 'utf8')
+}
+
+
+// The chosen representation, as a word - for generation logs and for the
+// per-SDK reporting the fleet regen needs, so a model crossing the threshold
+// is visible rather than showing up as an unexplained whole-file diff.
+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) }
 }