@voxgig/sdkgen 4.20.0 → 4.21.0

package/project/.sdk/src/cmp/perl/Schema_perl.ts

@@ -0,0 +1,107 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The perl 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 perl validates against and what ts validates against
+// cannot drift.
+//
+// EMBEDDED AS JSON, PARSED AT LOAD, in a heredoc, exactly as config.pm
+// carries its config — and here the parse is not merely convenient, it is the
+// point. Perl has no native boolean scalar, so a spec written as a perl
+// literal has to name Voxgig::Struct::JTRUE/JFALSE by hand at every boolean
+// slot (the hand-written optspec this replaces did); parse_json produces
+// those singletons itself, which is what `$BOOLEAN` matches against.
+//
+// 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.pm, and for the same reason: the generated data sits at the
+  // SDK root, so nothing under utility/ or feature/ has to reach up for it.
+  File({ name: 'schema.pm' }, () => {
+
+    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.
+
+use strict;
+use warnings;
+
+use File::Basename ();
+use Cwd ();
+
+my $__dir;
+BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
+require(Cwd::abs_path("$__dir/lib/Voxgig/Struct.pm"));
+
+package ${model.const.Name}Schema;
+
+my $OPTSPEC_JSON = <<'END_OPTSPEC_JSON';
+${JSON.stringify(optspec, null, 2)}
+END_OPTSPEC_JSON
+
+my $ENTITYSPEC_JSON = <<'END_ENTITYSPEC_JSON';
+${JSON.stringify(entityspec, null, 2)}
+END_ENTITYSPEC_JSON
+
+sub make_optspec {
+  return Voxgig::Struct::parse_json($OPTSPEC_JSON);
+}
+
+sub make_entityspec {
+  return Voxgig::Struct::parse_json($ENTITYSPEC_JSON);
+}
+
+# SHARED SPECS, the shape ${model.const.Name}Config::shared_config 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.
+#
+# The returned structures are SHARED: treat them as read-only. make_options
+# validates AGAINST the spec and writes into the options, never into the spec.
+my $SHARED_OPTSPEC;
+my $SHARED_ENTITYSPEC;
+
+sub optspec {
+  $SHARED_OPTSPEC = make_optspec() unless defined $SHARED_OPTSPEC;
+  return $SHARED_OPTSPEC;
+}
+
+sub entityspec {
+  $SHARED_ENTITYSPEC = make_entityspec() unless defined $SHARED_ENTITYSPEC;
+  return $SHARED_ENTITYSPEC;
+}
+
+1;
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/php/Main_php.ts

@@ -23,6 +23,7 @@ import {
 
 import { Package } from './Package_php'
 import { Config } from './Config_php'
+import { Schema } from './Schema_php'
 import { PrepareAuth } from './PrepareAuth_php'
 import { Gitignore } from './Gitignore_php'
 import { MainEntity } from './MainEntity_php'
@@ -104,6 +105,7 @@ const Main = cmp(async function Main(props: any) {
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
+    Schema({ target })
   })
 
   // GENERATED, NOT COPIED. Where the credential goes is a fact about the

package/project/.sdk/src/cmp/php/Package_php.ts

@@ -69,7 +69,7 @@ const Package = cmp(async function Package(props: any) {
   },
   "autoload": {
     "files": ["${model.const.Name.toLowerCase()}_sdk.php"],
-    "classmap": ["core/", "entity/", "feature/", "types/", "utility/", "config.php", "features.php"]
+    "classmap": ["core/", "entity/", "feature/", "types/", "utility/", "config.php", "schema.php", "features.php"]
   },
   "autoload-dev": {
     "classmap": ["test/"]

package/project/.sdk/src/cmp/php/ReadmeExplanation_php.ts

@@ -20,6 +20,7 @@ Use \`Helpers::to_map()\` to safely validate that a value is an array.
 php/
 ├── ${model.const.Name.toLowerCase()}_sdk.php          -- Main SDK class
 ├── config.php                     -- Configuration
+├── schema.php                     -- Generated option + entity specs
 ├── features.php                   -- Feature factory
 ├── core/                          -- Core types and context
 ├── entity/                        -- Entity implementations

package/project/.sdk/src/cmp/php/Schema_php.ts

@@ -0,0 +1,129 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+  rawStringLiteral,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The php 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 php validates against and what ts validates against cannot drift.
+//
+// EMBEDDED AS JSON, DECODED ON FIRST USE, the mechanism config.php already
+// uses for the model above the size threshold, and SINGLE-quoted for the
+// reason recorded there: a double-quoted php string would interpolate a `$`,
+// and the spec is made almost entirely of `$SENTINEL` strings.
+//
+// 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) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`<?php
+declare(strict_types=1);
+
+// ${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.
+
+class ${model.const.Name}Schema
+{
+    private const OPTSPEC_DATA = ${rawStringLiteral(JSON.stringify(optspec))};
+
+    private const ENTITYSPEC_DATA = ${rawStringLiteral(JSON.stringify(entityspec))};
+
+    // A UNION, not ?array. schema_decode hands back an empty stdClass for an
+    // EMPTY map - that is the whole point of decoding without the assoc flag,
+    // since php cannot otherwise tell an empty map from an empty list - and
+    // the entity specs are empty for a project with no entities, and whenever
+    // the validate feature is inactive, which is the default. Typed ?array,
+    // the first call to entityspec() threw a TypeError instead of handing
+    // back the empty map every other target returns.
+    private static array|\\stdClass|null $optspec = null;
+
+    private static array|\\stdClass|null $entityspec = null;
+
+    // Decoded ONCE, on first use. The spec is read on every client
+    // construction and never mutated, so decoding per call would be pure
+    // waste — and sharing the array is safe for the same reason:
+    // make_options validates AGAINST it and writes into the options, never
+    // into the spec. (php arrays are copy-on-write, so a caller that did
+    // write would get its own copy rather than corrupt this one.)
+    public static function optspec(): array|\\stdClass
+    {
+        if (self::$optspec === null) {
+            self::$optspec = self::schema_decode(json_decode(self::OPTSPEC_DATA));
+        }
+        return self::$optspec;
+    }
+
+    public static function entityspec(): array|\\stdClass
+    {
+        if (self::$entityspec === null) {
+            self::$entityspec = self::schema_decode(json_decode(self::ENTITYSPEC_DATA));
+        }
+        return self::$entityspec;
+    }
+
+    /**
+     * Decode WITHOUT the assoc flag, then convert — for the one reason
+     * config.php decodes the same way.
+     *
+     * php has a single array type, so json_decode with the assoc flag
+     * renders an empty object and an empty list identically. Struct tells a
+     * map from a list, so every empty map in the spec — utility, a feature's
+     * rates, the OPEN-only entity template — arrived as an empty LIST and
+     * was rejected with "Expected map, but found no value". Decoding to
+     * stdClass keeps the distinction long enough to preserve it.
+     *
+     * config.php patches its two known empty maps by hand afterwards; the
+     * spec has too many to enumerate and would gain one whenever a feature
+     * declares a map option, so this restores every one of them by shape.
+     */
+    private static function schema_decode(mixed $v): mixed
+    {
+        if ($v instanceof \\stdClass) {
+            $vars = get_object_vars($v);
+            if (count($vars) === 0) {
+                return (object)[];
+            }
+            $out = [];
+            foreach ($vars as $k => $c) {
+                $out[$k] = self::schema_decode($c);
+            }
+            return $out;
+        }
+        if (is_array($v)) {
+            return array_map([self::class, 'schema_decode'], $v);
+        }
+        return $v;
+    }
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/py/Main_py.ts

@@ -24,6 +24,7 @@ import {
 
 import { Package } from './Package_py'
 import { Config } from './Config_py'
+import { Schema } from './Schema_py'
 import { PrepareAuth } from './PrepareAuth_py'
 import { Gitignore } from './Gitignore_py'
 import { MainEntity } from './MainEntity_py'
@@ -189,6 +190,7 @@ if TYPE_CHECKING:
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
+    Schema({ target })
   })
 
   // GENERATED, NOT COPIED. Where the credential goes is a fact about the

package/project/.sdk/src/cmp/py/ReadmeExplanation_py.ts

@@ -20,6 +20,7 @@ Use \`helpers.to_map()\` to safely validate that a value is a dict.
 py/
 ├── ${model.const.Name.toLowerCase()}_sdk.py         -- Main SDK module
 ├── config.py                    -- Configuration
+├── schema.py                    -- Generated option + entity specs
 ├── features.py                  -- Feature factory
 ├── core/                        -- Core types and context
 ├── entity/                      -- Entity implementations

package/project/.sdk/src/cmp/py/Schema_py.ts

@@ -0,0 +1,72 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The python 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 python validates against and what ts validates against
+// cannot drift.
+//
+// EMBEDDED AS JSON, PARSED AT IMPORT, the same mechanism config.py already
+// uses for the model above the size threshold. A python dict literal would
+// also work here, but `json.loads` (the C accelerator) builds it from one
+// string constant rather than making the byte-compiler walk several hundred
+// literal nodes, and it is the one mechanism every ported target shares.
+//
+// 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. JSON's single number type is the hazard that
+// test exists for: `true`/`false` and `null` differ between JSON and python
+// source, which is why this is a parsed string and not a literal paste.
+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(`# ${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.
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+_OPTSPEC_DATA = ${JSON.stringify(JSON.stringify(optspec))}
+
+_ENTITYSPEC_DATA = ${JSON.stringify(JSON.stringify(entityspec))}
+
+# Parsed ONCE, at import. The spec is read on every client construction and
+# never mutated, so a per-call parse would be pure waste — and sharing the
+# dict is safe for the same reason: make_options validates AGAINST it and
+# writes into the options, never into the spec.
+OPTSPEC: Dict[str, Any] = json.loads(_OPTSPEC_DATA)
+
+ENTITYSPEC: Dict[str, Any] = json.loads(_ENTITYSPEC_DATA)
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/rb/Main_rb.ts

@@ -23,6 +23,7 @@ import {
 
 import { Package } from './Package_rb'
 import { Config } from './Config_rb'
+import { Schema } from './Schema_rb'
 import { PrepareAuth } from './PrepareAuth_rb'
 import { Gitignore } from './Gitignore_rb'
 import { MainEntity } from './MainEntity_rb'
@@ -95,6 +96,7 @@ utility.feature_hook.call(@_rootctx, "${name}")
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
+    Schema({ target })
   })
 
   // GENERATED, NOT COPIED. Where the credential goes is a fact about the

package/project/.sdk/src/cmp/rb/ReadmeExplanation_rb.ts

@@ -20,6 +20,7 @@ Use \`Helpers.to_map()\` to safely validate that a value is a hash.
 rb/
 ├── ${model.const.Name}_sdk.rb       -- Main SDK module
 ├── config.rb                  -- Configuration
+├── schema.rb                  -- Generated option + entity specs
 ├── features.rb                -- Feature factory
 ├── core/                      -- Core types and context
 ├── entity/                    -- Entity implementations

package/project/.sdk/src/cmp/rb/Schema_rb.ts

@@ -0,0 +1,70 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+  rawStringLiteral,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The ruby 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 ruby validates against and what ts validates against cannot drift.
+//
+// EMBEDDED AS JSON, PARSED AT LOAD, the mechanism config.rb already uses for
+// the model above the size threshold, and SINGLE-quoted for the reason
+// recorded there: a double-quoted ruby string would interpolate any `#{` the
+// model happens to contain.
+//
+// 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) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`# ${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.
+
+require 'json'
+
+module ${model.const.Name}Schema
+
+  OPTSPEC_DATA = ${rawStringLiteral(JSON.stringify(optspec))}.freeze
+
+  ENTITYSPEC_DATA = ${rawStringLiteral(JSON.stringify(entityspec))}.freeze
+
+  # Parsed ONCE, at load. The spec is read on every client construction and
+  # never mutated, so a per-call parse would be pure waste — and sharing the
+  # hash is safe for the same reason: make_options validates AGAINST it and
+  # writes into the options, never into the spec.
+  OPTSPEC = JSON.parse(OPTSPEC_DATA).freeze
+
+  ENTITYSPEC = JSON.parse(ENTITYSPEC_DATA).freeze
+
+end
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/rust/Main_rust.ts

@@ -24,6 +24,7 @@ import {
 
 import { Package } from './Package_rust'
 import { Config } from './Config_rust'
+import { Schema } from './Schema_rust'
 import { PrepareAuth } from './PrepareAuth_rust'
 import { Gitignore } from './Gitignore_rust'
 import { MainEntity } from './MainEntity_rust'
@@ -109,6 +110,8 @@ const Main = cmp(async function Main(props: any) {
 
     Config({ target })
 
+    Schema({ target })
+
     SdkError({ target })
   })
 

package/project/.sdk/src/cmp/rust/Schema_rust.ts

@@ -0,0 +1,107 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  rustRawString,
+} from './utility_rust'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The rust 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 rust 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 rust's.
+// A raw string, exactly as config.rs carries its data rep above the size
+// threshold; the spec has no threshold because it is bounded by the option
+// list and the feature set rather than by the API.
+//
+// No number-type question here, unlike Go: `Value::Num` is f64 whichever way
+// it is built. The spec holds only strings and booleans anyway, 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.rs, 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.
+
+use crate::utility::jsonparse::json_parse;
+use crate::utility::voxgigstruct::Value;
+
+const OPTSPEC_DATA: &str = ${rustRawString(JSON.stringify(optspec))};
+
+const ENTITYSPEC_DATA: &str = ${rustRawString(JSON.stringify(entityspec))};
+
+/// The option spec make_options validates client options against.
+///
+/// Unreachable on error: the constant is generated by a JSON serialiser and
+/// never edited by hand. Panicking beats returning an empty spec, which would
+/// validate everything and fail far from the cause.
+pub fn make_optspec() -> Value {
+    json_parse(OPTSPEC_DATA).expect("${model.const.Name}: embedded option spec is not valid JSON")
+}
+
+/// Per-entity data and request specs, keyed by entity name.
+pub fn make_entityspec() -> Value {
+    json_parse(ENTITYSPEC_DATA).expect("${model.const.Name}: embedded entity spec is not valid JSON")
+}
+
+// SHARED SPECS, the shape core::config::shared_config 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 — and THREAD-LOCAL rather than
+// global, because Value is Rc/RefCell-backed and so is neither Send nor Sync.
+// The clone is an Rc bump, not a deep copy.
+//
+// The returned Value SHARES its nodes: treat it as read-only. make_options
+// validates AGAINST the spec and writes into the options, never into the spec.
+thread_local! {
+    static SHARED_OPTSPEC: Value = make_optspec();
+    static SHARED_ENTITYSPEC: Value = make_entityspec();
+}
+
+/// The per-thread option spec, built once on first use.
+pub fn optspec() -> Value {
+    SHARED_OPTSPEC.with(|s| s.clone())
+}
+
+/// The per-thread entity specs, built once on first use.
+pub fn entityspec() -> Value {
+    SHARED_ENTITYSPEC.with(|s| s.clone())
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/scala/Main_scala.ts

@@ -23,6 +23,7 @@ import {
 
 import { Package } from './Package_scala'
 import { Config } from './Config_scala'
+import { Schema } from './Schema_scala'
 import { Gitignore } from './Gitignore_scala'
 import { MainEntity } from './MainEntity_scala'
 import { EntityBase } from './EntityBase_scala'
@@ -201,6 +202,8 @@ const Main = cmp(async function Main(props: any) {
 
     Config({ target })
 
+    Schema({ target })
+
     // Generate the typed reference-model file (<Name>Types.scala) beside the
     // other generated core files. Documentation/DX shapes only — not wired
     // into the loose-object-model op signatures.