@voxgig/sdkgen 4.20.0 → 4.21.0

package/project/.sdk/src/cmp/cpp/Schema_cpp.ts

@@ -0,0 +1,105 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  cppConfigLiterals,
+} from './utility_cpp'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The cpp peer of src/cmp/ts/Schema_ts.ts. Same two members, same source:
+// optspec from `main.kit.optspec` plus each feature's own `config.options`,
+// entityspec from the entity field sentinels — both built by the shared
+// helpers, so what cpp validates against and what ts validates against cannot
+// drift.
+//
+// EMBEDDED AS JSON, PARSED AT LOAD, where ts emits an object literal: JSON is
+// a subset of TypeScript's own literal syntax and is not a subset of cpp's.
+// Chunked adjacent string literals, exactly as config.hpp carries its config,
+// so no single literal approaches an implementation's minimum-supported
+// length however large the model grows.
+//
+// This REPLACES the OPTSPEC_JSON() that used to sit in pipeline.hpp — a
+// hand-maintained copy of the spec that nothing cross-checked, and which had
+// already drifted (no `extend`, no `server`, no `auth.basic`).
+//
+// The round-trip is exact because the spec holds only strings and booleans:
+// pinned by "strings and booleans only, so the JSON round-trip is lossless"
+// in ts/test/optspec.test.ts.
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  // Beside config.hpp, in core, and for the same reason: core owns the
+  // generated data, so nothing in utility or feature has to reach up for it.
+  File({ name: 'schema.' + target.ext }, () => {
+
+    Content(`// ${model.const.Name} SDK: generated schemas. Do not edit.
+//
+// Built from the model: \`main.kit.optspec\` and each feature's
+// \`config.options\` for the option spec; entity \`fields[].type\` for the
+// entity specs.
+
+#ifndef SDK_CORE_SCHEMA_HPP
+#define SDK_CORE_SCHEMA_HPP
+
+#include "../core/struct.hpp"
+
+namespace sdk {
+
+inline const char* optspec_json() {
+  return
+${cppConfigLiterals(optspec)};
+}
+
+inline const char* entityspec_json() {
+  return
+${cppConfigLiterals(entityspec)};
+}
+
+// SHARED SPECS, the shape sharedConfig uses and for the same reasons: the
+// spec is read on every client construction and never mutated, so a per-call
+// parse would be pure waste. A function-local static in an inline function is
+// one object across every translation unit, and its initialisation is
+// thread-safe by the standard.
+//
+// The results are SHARED: treat them as read-only. makeOptions validates
+// AGAINST the spec and writes into the options, never into the spec.
+inline const Value& sharedOptspec() {
+  static const Value shared = vs::parse_json(optspec_json());
+  return shared;
+}
+
+inline const Value& sharedEntityspec() {
+  static const Value shared = vs::parse_json(entityspec_json());
+  return shared;
+}
+
+}  // namespace sdk
+
+#endif  // SDK_CORE_SCHEMA_HPP
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/csharp/Main_csharp.ts

@@ -22,6 +22,7 @@ import {
 
 import { Package } from './Package_csharp'
 import { Config } from './Config_csharp'
+import { Schema } from './Schema_csharp'
 import { PrepareAuth } from './PrepareAuth_csharp'
 import { Gitignore } from './Gitignore_csharp'
 import { MainEntity } from './MainEntity_csharp'
@@ -107,6 +108,8 @@ const Main = cmp(async function Main(props: any) {
 
     Config({ target })
 
+    Schema({ target })
+
     SdkError({ target })
 
     EntityBase({ target })

package/project/.sdk/src/cmp/csharp/Schema_csharp.ts

@@ -0,0 +1,85 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  formatCsMap,
+} from './utility_csharp'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The csharp peer of src/cmp/ts/Schema_ts.ts. Same two members, same source:
+// Optspec from `main.kit.optspec` plus each feature's own `config.options`,
+// Entityspec from the entity field sentinels — both built by the shared
+// helpers, so what csharp validates against and what ts validates against
+// cannot drift.
+//
+// A COLLECTION LITERAL, not embedded JSON, where go and the JVM targets
+// parse a string. SdkConfig switches to a JSON constant above a size
+// threshold because a large composite literal is slow for the compiler to
+// bind and the JIT to run; the spec has no such spread. It is bounded by the
+// option list and the feature set — a few hundred entries whatever the API
+// looks like — and in C# the literal is also the SAFER rep: a `false` here
+// stays `false` rather than arriving as a JsonElement to be mapped back, and
+// the number ladder SdkConfig's ConfigValue exists to reproduce is a question
+// the spec never asks (it holds only strings and booleans, pinned by "strings
+// and booleans only" in ts/test/optspec.test.ts).
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  // Beside Config.cs, and for the same reason: core owns the generated data,
+  // so nothing in the copied runtime has to reach up for it.
+  File({ name: 'Schema.' + target.ext }, () => {
+
+    Content(`// ${model.const.Name} SDK - generated schemas. GENERATED from the API model -
+// do not edit by hand.
+//
+// Built from the model: \`main.kit.optspec\` and each feature's
+// \`config.options\` for Optspec; entity \`fields[].type\` for Entityspec.
+
+namespace ${model.const.Name}Sdk;
+
+public static class SdkSchema
+{
+    // Built ONCE, on first use. The spec is read on every client construction
+    // and never mutated, so rebuilding it per call would be pure waste — and
+    // a shared dictionary is safe for the same reason the spec is a constant:
+    // MakeOptions validates AGAINST it and writes into the options, never
+    // into the spec.
+    //
+    // A static field initializer, so the CLR's type initializer gives the
+    // once-only, thread-safe guarantee with no locking on the read path.
+
+    /// <summary>The option spec MakeOptions validates client options against.</summary>
+    public static readonly Dictionary<string, object?> Optspec =
+        ${formatCsMap(optspec, 2)};
+
+    /// <summary>Per-entity data and request specs, keyed by entity name.</summary>
+    public static readonly Dictionary<string, object?> Entityspec =
+        ${formatCsMap(entityspec, 2)};
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/elixir/Main_elixir.ts

@@ -17,6 +17,7 @@ import {
 
 import { Package } from './Package_elixir'
 import { Config } from './Config_elixir'
+import { Schema } from './Schema_elixir'
 import { PrepareAuth } from './PrepareAuth_elixir'
 import { Gitignore } from './Gitignore_elixir'
 import { MainEntity } from './MainEntity_elixir'
@@ -174,6 +175,7 @@ end
 
   // Config module.
   Config({ target })
+  Schema({ target })
 })
 
 

package/project/.sdk/src/cmp/elixir/ReadmeExplanation_elixir.ts

@@ -26,6 +26,7 @@ elixir/
 ├── lib/
 │   ├── ${app}.ex                 -- Main SDK module (entity factories)
 │   ├── config.ex                 -- Resolved configuration
+│   ├── schema.ex                 -- Generated option + entity specs
 │   ├── features.ex               -- Feature factory
 │   ├── pipeline.ex               -- Operation pipeline
 │   └── ${app}/

package/project/.sdk/src/cmp/elixir/Schema_elixir.ts

@@ -0,0 +1,88 @@
+import {
+  Content,
+  File,
+  Folder,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  elixirString,
+} from './utility_elixir'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The elixir peer of src/cmp/ts/Schema_ts.ts. Same two exports, same source —
+// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
+// ENTITYSPEC from the entity field sentinels — built by the shared helpers,
+// so what elixir validates against and what ts validates against cannot
+// drift.
+//
+// EMBEDDED AS JSON IN A MODULE ATTRIBUTE, PARSED AT COMPILE TIME, exactly as
+// config.ex carries the model. `elixirString` escapes every `#` for the
+// reason recorded there: elixir interpolates `#{...}` inside a double-quoted
+// string, so an unescaped one would be evaluated as code rather than emitted
+// as text.
+//
+// The round-trip is exact because the spec holds only strings and booleans —
+// pinned by "strings and booleans only, so the JSON round-trip is lossless"
+// in ts/test/optspec.test.ts.
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+  const Name = model.const.Name
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  // UNDER lib/, like config.ex and for a reason that bites immediately: mix's
+  // `elixirc_paths` is ["lib"] (plus test/ under :test), so a module at the
+  // SDK ROOT is never compiled. This file used to be emitted there, and
+  // `Schema.optspec/0` was therefore undefined in every generated elixir SDK
+  // — make_options raised UndefinedFunctionError on the first client
+  // construction. The elixir compile lane skips where no toolchain is
+  // installed, so nothing caught it.
+  Folder({ name: 'lib' }, () => {
+
+  File({ name: 'schema.ex' }, () => {
+    Content(`# ${Name} ${target.Name} SDK: generated schemas. Do not edit.
+#
+# Generated from the model: \`main.kit.optspec\` and each feature's
+# \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+
+defmodule ${Name}.Schema do
+  @optspec_data ${elixirString(JSON.stringify(optspec))}
+
+  @entityspec_data ${elixirString(JSON.stringify(entityspec))}
+
+  # Parsed at COMPILE time and held as a literal: the spec is read on every
+  # client construction and never mutated, so parsing per call would be pure
+  # waste, and elixir terms are immutable so sharing carries no risk at all.
+  @optspec ${Name}.Json.parse(@optspec_data)
+
+  @entityspec ${Name}.Json.parse(@entityspec_data)
+
+  def optspec, do: @optspec
+
+  def entityspec, do: @entityspec
+end
+`)
+  })
+
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/go/Main_go.ts

@@ -24,6 +24,7 @@ import {
 import { goFeatureName } from './utility_go'
 import { Package } from './Package_go'
 import { Config } from './Config_go'
+import { Schema } from './Schema_go'
 import { Gitignore } from './Gitignore_go'
 import { MainEntity } from './MainEntity_go'
 import { EntityTypes } from './EntityTypes_go'
@@ -131,6 +132,7 @@ s.utility.FeatureHook(s.rootctx, "${name}")
     })
 
     Config({ target })
+    Schema({ target })
 
     // Generate registry.go with all constructor function vars
     File({ name: 'registry.' + target.ext }, () => {

package/project/.sdk/src/cmp/go/Schema_go.ts

@@ -0,0 +1,93 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  formatGoString,
+} from './utility_go'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The go peer of src/cmp/ts/Schema_ts.ts. Same two exports, same source:
+// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
+// ENTITYSPEC from the entity field sentinels — both built by the shared
+// helpers, so what go validates against and what ts validates against cannot
+// drift.
+//
+// EMBEDDED AS JSON, PARSED AT LOAD, where ts emits an object literal. JSON is
+// a subset of TypeScript's own literal syntax and is not a subset of go's, so
+// the literal ts writes directly is a `map[string]any{...}` tree here — which
+// this could render (utility_go has the formatter config.go's literal branch
+// uses), but the JSON string is the smaller, simpler artefact and every
+// target this is being ported to already carries one for its config.
+//
+// The round-trip is exact because the spec holds only strings and booleans:
+// pinned by "strings and booleans only, so the JSON round-trip is lossless"
+// in ts/test/optspec.test.ts. That is not incidental. json.Unmarshal decodes
+// EVERY JSON number as float64, and struct reads a spec by example, so one
+// number in here would mean something different in go than in ts — the same
+// disagreement configNormalise exists to repair in config.go.
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`package core
+
+import (
+	"encoding/json"
+)
+
+// ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+//
+// Generated from the model: \`main.kit.optspec\` and each feature's
+// \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+
+const optspecJSON = ${formatGoString(JSON.stringify(optspec))}
+
+const entityspecJSON = ${formatGoString(JSON.stringify(entityspec))}
+
+// Parsed ONCE, at package init. The spec is read on every client
+// construction and never mutated, so a per-call parse would be pure waste —
+// and a shared map is safe here for the same reason the spec is a constant:
+// MakeOptions validates AGAINST it and writes into the options, never into
+// the spec.
+var (
+	OPTSPEC    = mustSpec(optspecJSON)
+	ENTITYSPEC = mustSpec(entityspecJSON)
+)
+
+func mustSpec(src string) map[string]any {
+	var out map[string]any
+	if err := json.Unmarshal([]byte(src), &out); err != nil {
+		// Unreachable: generated by json.Marshal's counterpart and never
+		// edited by hand. Panic rather than hand back an empty spec, which
+		// would validate everything and fail far from the cause.
+		panic("${model.const.Name}: embedded schema is not valid JSON: " + err.Error())
+	}
+	return out
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/java/Main_java.ts

@@ -23,6 +23,7 @@ import {
 
 import { Package } from './Package_java'
 import { Config } from './Config_java'
+import { Schema } from './Schema_java'
 import { Gitignore } from './Gitignore_java'
 import { MainEntity } from './MainEntity_java'
 import { EntityBase } from './EntityBase_java'
@@ -119,6 +120,7 @@ this.utility.featureHook.apply(this.rootctx, "${name}");
     })
 
     Config({ target })
+    Schema({ target })
 
     // Generate the typed reference-model file (<Name>Types.java) beside the
     // other generated core files. Documentation/DX shapes only — not wired

package/project/.sdk/src/cmp/java/Schema_java.ts

@@ -0,0 +1,125 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  javaPackage,
+  jsonAppendLines,
+} from './utility_java'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The java peer of src/cmp/ts/Schema_ts.ts. Same two members, same source:
+// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
+// ENTITYSPEC from the entity field sentinels — both built by the shared
+// helpers, so what java validates against and what ts validates against
+// cannot drift.
+//
+// EMBEDDED AS JSON, PARSED AT LOAD, where ts emits an object literal: JSON is
+// a subset of TypeScript's own literal syntax and is not a subset of java's.
+// Chunked StringBuilder appends, exactly as Config.java carries its config,
+// keep every string constant far below the JVM's 64KB limit no matter how
+// many features or entities the model grows.
+//
+// The round-trip is exact because the spec holds only strings and booleans:
+// pinned by "strings and booleans only, so the JSON round-trip is lossless"
+// in ts/test/optspec.test.ts. That is not incidental — Json.parse decodes a
+// JSON number to one java type and struct reads a spec BY EXAMPLE, so one
+// number in here would mean something different in java than in ts.
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+  const javapackage = javaPackage(model)
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  // Beside Config.java, and for the same reason: core owns the generated
+  // data, so nothing in utility or feature has to reach up for it.
+  File({ name: 'Schema.' + target.ext }, () => {
+
+    Content(`package ${javapackage}.core;
+
+import java.util.Map;
+
+import ${javapackage}.utility.Json;
+
+/**
+ * ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+ *
+ * <p>Generated from the model: {@code main.kit.optspec} and each feature's
+ * {@code config.options} for OPTSPEC; entity {@code fields[].type} for
+ * ENTITYSPEC.
+ */
+@SuppressWarnings({"unchecked"})
+public final class Schema {
+
+  private Schema() {}
+
+  // Parsed ONCE, on first use. The spec is read on every client construction
+  // and never mutated, so a per-call parse would be pure waste — and a shared
+  // map is safe for the same reason the spec is a constant: MakeOptions
+  // validates AGAINST it and writes into the options, never into the spec.
+  //
+  // Initialization-on-demand holder, as Config.sharedConfig uses: the JLS
+  // guarantees the class initializer runs once, lazily, and safely under
+  // concurrency, with no locking on the read path.
+  private static final class OptHolder {
+    static final Map<String, Object> VALUE =
+        (Map<String, Object>) Json.parse(optspecJson());
+  }
+
+  private static final class EntityHolder {
+    static final Map<String, Object> VALUE =
+        (Map<String, Object>) Json.parse(entityspecJson());
+  }
+
+  /** The option spec MakeOptions validates client options against. */
+  public static Map<String, Object> optspec() {
+    return OptHolder.VALUE;
+  }
+
+  /** Per-entity data and request specs, keyed by entity name. */
+  public static Map<String, Object> entityspec() {
+    return EntityHolder.VALUE;
+  }
+
+  private static String optspecJson() {
+    StringBuilder b = new StringBuilder();
+`)
+
+    Content(jsonAppendLines(optspec, 'b'))
+
+    Content(`    return b.toString();
+  }
+
+  private static String entityspecJson() {
+    StringBuilder b = new StringBuilder();
+`)
+
+    Content(jsonAppendLines(entityspec, 'b'))
+
+    Content(`    return b.toString();
+  }
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/kotlin/Main_kotlin.ts

@@ -22,6 +22,7 @@ import {
 
 import { Package } from './Package_kotlin'
 import { Config } from './Config_kotlin'
+import { Schema } from './Schema_kotlin'
 import { Gitignore } from './Gitignore_kotlin'
 import { MainEntity } from './MainEntity_kotlin'
 import { EntityBase } from './EntityBase_kotlin'
@@ -136,6 +137,7 @@ const Main = cmp(async function Main(props: any) {
     })
 
     Config({ target })
+    Schema({ target })
 
     // Generate the typed reference-model file (<Name>Types.kt) beside the
     // other generated core files. Documentation/DX shapes only — not wired