@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/src/cmp/lua/ReadmeModel_lua.ts

@@ -13,10 +13,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
-  // Model-driven op rows for the shared entity interface: emit a
-  // load/list/create/update/remove row only for operations at least one active
-  // entity actually exposes (a read-only entity has just list+load) — never
-  // document an operation no entity has.
   const opUnion = new Set<string>()
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
@@ -30,9 +26,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const opRows = ['load', 'list', 'create', 'update', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
-  // Model-driven Result-shape rows: only describe the operations that
-  // actually exist. Record-returning ops (load/create/update/remove) share
-  // one row; list has its own — never name a missing op.
   const recordOps = ['load', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o + '`')
   const resultRows: string[] = []
@@ -50,8 +43,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const eName = exEnt.Name || 'Entity'
   const eLower = String(exEnt.name || 'entity').toLowerCase()
   const hasLoad = null != (exEnt.op || {}).load
-  // Model-driven id key: null when the example entity has no id-like field, so
-  // the Result-shape load illustration takes no match argument.
   const idF = entityIdField(exEnt)
 
   const apikeyOptionRow = isAuthActive(model)
@@ -136,7 +127,6 @@ Only \`direct()\` returns a response envelope — a \`table\` with \`ok\`,
 
 `)
 
-  // Entities summary
   Content(`### Entities
 
 `)

package/project/.sdk/src/cmp/lua/ReadmeQuick_lua.ts

@@ -15,9 +15,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available: one with a parent chain
-  // (relations.ancestors), an active load op, and a required non-id load
-  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
     e.active !== false &&
     e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
@@ -108,9 +105,6 @@ end
       const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
       const neVar = exampleVarName(neName.toLowerCase(), 'lua')
 
-      // Model-driven match: every REQUIRED load-match key — the same shape
-      // the runtime resolves path params from, so the example always works.
-      // Parent keys (e.g. page_id) first, the entity's own id last.
       const neIdF = entityIdField(nestedEntity)
       const neRequired = opRequestShape(nestedEntity, 'load').items
         .filter((it: any) => !it.optional)
@@ -136,9 +130,6 @@ print(${neVar})
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -160,20 +151,12 @@ print(${eVar})
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields, not a
-    // hardcoded "name" the entity may not have. Literals are Lua-typed by the
-    // field's canonical type; non-identifier keys use bracket syntax. ids are
-    // rendered separately as the match key for update/remove; a REQUIRED
-    // create id stays (the call is invalid without it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => !idNames.has(it.name) ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields; update is a patch, so the required
-      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
@@ -181,8 +164,6 @@ print(${eVar})
         `${luaKey(it.name)} = ${luaLit(it.type, 'example_' + it.name)}`)
     }
 
-    // The id VALUE for an update/remove match: off the returned `created` record
-    // only when its data type carries the id AND a create ran, else a literal.
     const idParamType = (opname: string): any => {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
@@ -211,8 +192,6 @@ client:${eName}():update({ ${updatePairs.join(', ')} })
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/lua/ReadmeRef_lua.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, luaKey , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -57,7 +57,7 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const { model } = props.ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  const feature = targetFeatures(model, target)
 
   const publishedEntities = each(entity).filter((e: any) => e.active !== false)
 
@@ -119,7 +119,6 @@ local client = sdk.test()
 `)
 
 
-    // Entity factory methods
     publishedEntities.map((ent: any) => {
       Content(`#### \`${ent.Name}(data)\`
 
@@ -165,7 +164,6 @@ same parameters as \`direct()\`.
 `)
 
 
-    // Entity reference sections
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
@@ -196,7 +194,6 @@ local ${eVar} = client:${ent.Name}(nil)
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -243,7 +240,6 @@ local ${eVar} = client:${ent.Name}(nil)
       }
 
 
-      // Operation details
       if (opnames.length > 0) {
         Content(`### Operations
 
@@ -259,7 +255,6 @@ ${info.desc}
 
 `)
 
-          // Show example
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
             // like page_id) — the same shape the runtime resolves path
@@ -328,7 +323,6 @@ ${updateLines}  -- Fields to update
       }
 
 
-      // Common methods
       Content(`### Common Methods
 
 #### \`data_get() -> table\`
@@ -360,7 +354,6 @@ Return the entity name.
     })
 
 
-    // Features section
     const activeFeatures = each(feature).filter((f: any) => f.active)
     if (activeFeatures.length > 0) {
       Content(`
@@ -396,9 +389,6 @@ local client = sdk.new({
 \`\`\`
 
 `)
-      // The shared feature reference: options, defaults, usage and the
-      // considerations. Model facts, identical in every target, so they are
-      // written once in cmp/ReadmeRefFeatures.ts rather than here.
       ReadmeRefFeatures({ target })
     }
 

package/project/.sdk/src/cmp/lua/ReadmeTopQuick_lua.ts

@@ -19,7 +19,6 @@ function luaLit(type: any, placeholder: string = 'example'): string {
   return `"${placeholder}"`
 }
 
-// Non-identifier table keys use bracket syntax.
 
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
@@ -47,8 +46,6 @@ local client = ${ctor}
     // Lua keyword (e.g. `end`) would otherwise emit uncompilable code.
     const eVar = exampleVarName(eName.toLowerCase(), 'lua')
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes no match argument.
     const idF = entityIdField(exampleEntity)
 
     let hasCall = false

package/project/.sdk/src/cmp/lua/Schema_lua.ts

@@ -0,0 +1,56 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  luaLongString,
+} from './utility_lua'
+
+
+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.
+
+local json = require("dkjson")
+
+local OPTSPEC_DATA = ${luaLongString(JSON.stringify(optspec))}
+
+local ENTITYSPEC_DATA = ${luaLongString(JSON.stringify(entityspec))}
+
+-- Parsed ONCE, at require. The spec is read on every client construction and
+-- never mutated, so a per-call parse would be pure waste — and sharing the
+-- table is safe for the same reason: make_options validates AGAINST it and
+-- writes into the options, never into the spec.
+return {
+  OPTSPEC = json.decode(OPTSPEC_DATA),
+  ENTITYSPEC = json.decode(ENTITYSPEC_DATA),
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/lua/TestDirect_lua.ts

@@ -251,8 +251,6 @@ ${listSkipBlock}    local client = setup.client
     }
 
     if (hasLoad && loadPoint) {
-      // Skip live direct-load only when we can't fill path params:
-      // no spec examples and no list-bootstrap. Spec examples win first.
       const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
         ? `    if setup.live then
       pending("live direct-load needs real ID — set *_ENTID env var with real IDs to run")

package/project/.sdk/src/cmp/lua/utility_lua.ts

@@ -66,28 +66,6 @@ function formatLuaValue(val: any, indent: number = 0): string {
 }
 
 
-// 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
@@ -128,14 +106,6 @@ function clean(o: any, dropDefaults?: boolean): any {
 
 
 
-// A Lua LONG-BRACKET string holding `s` verbatim.
-//
-// Lua's quoted strings process escapes, so the JSON's own `\n` and `\uXXXX`
-// would be consumed by the Lua lexer before the JSON decoder ever saw them -
-// turning an escaped newline into a real one inside a JSON string (invalid
-// JSON), and failing outright on `\uXXXX`, which Lua 5.1/5.2 do not accept at
-// all. A long bracket processes nothing, so the JSON text survives byte for
-// byte. The level is raised until its terminator does not occur in the text.
 function luaLongString(s: string): string {
   let level = 0
   while (s.includes(']' + '='.repeat(level) + ']')) {

package/project/.sdk/src/cmp/ocaml/Config_ocaml.ts

@@ -28,40 +28,12 @@ import {
 } from './utility_ocaml'
 
 
-// THE SECRETS BUILD MODEL, derived from the model ONCE and read by both the
-// Makefile fragment (Main_ocaml emits feature/secrets/feature.mk from it)
-// and the generated config (the definitions list and the bundled transport
-// below), so the two cannot disagree about which kinds are compiled.
-//
-// Upstream sekreto retired its self-registration registry for voxgig/plugin
-// definitions: a provider kind the caller did not pass in `~plugins` is
-// unknown to that Sekreto. So the model's choice of plugin groups IS the
-// SDK's provider vocabulary, and the generated code names each active
-// group's constructor (`def: ocaml:` in model/feature/secrets.aon -
-// `Hashicorp.plugin`, the `unit -> Defs.definition` each vendored kind
-// module defines) and nothing else. A symbol named here whose module the
-// plugin trim removed is an "Unbound module" at compile time - a loud
-// failure, which is the right kind.
-//
-// MODULE ORDER IS THE DEPENDENCY ORDER, written down (upstream's own
-// Makefile is the source): the voxgig/plugin host, the sekreto core, the
-// shared helpers, the kinds. The helpers are ungrouped in the model (see the
-// ocaml note at the head of its `plugin` block) and are listed here only
-// when a selected kind needs them - the transport chain (crypto, sigv4, tls,
-// http, httpjson) when an active group declares `needs.fetch`, the
-// child-process helper (runcmd) when any kind is on - because OCaml
-// compiles exactly what it is handed: an [env, memory] chain compiles the
-// two cores alone, and `secretspec` alone compiles runcmd.ml and no TLS.
-//
-// Null when the model does not activate `secrets` for this target. Read
-// with `only_active: false` on the plugin map (pluginExcludesFor's
-// subtlety: the feature object a component is handed has already been
-// filtered, so a feature whose groups are all off would look like one
-// with no plugin machinery).
 type SecretsBuild = {
   groups: string[],
   tlsGroups: string[],
   tls: boolean,
+  stubs: string[],
+  stubGroups: string[],
   plugin: string[],
   core: string[],
   helpers: string[],
@@ -93,6 +65,8 @@ function secretsBuild(model: Model, target: any): SecretsBuild | null {
 
   const groups: string[] = []
   const tlsGroups: string[] = []
+  const stubGroups: string[] = []
+  const stubs = new Set<string>()
   const syms = new Set<string>()
   const kinds = new Set<string>()
 
@@ -105,6 +79,17 @@ function secretsBuild(model: Model, target: any): SecretsBuild | null {
     if (0 === Object.keys(defs).length) return
     groups.push(plugin.name)
     if (true === plugin.needs?.fetch) tlsGroups.push(plugin.name)
+
+    // `stub`, keyed by TARGET - not a filter over `path`, which is one flat
+    // list across every target: ocaml's minivault_stubs.c sits beside c's
+    // boru.c and hashicorp.c, and a prefix filter handed this build both of
+    // them. Declared per target, so what ocaml compiles is what the model
+    // says ocaml compiles.
+    const own = (plugin.stub?.[target.name] || []).map((one: any) => String(one))
+    if (0 < own.length) {
+      stubGroups.push(plugin.name)
+      for (const one of own) stubs.add(one)
+    }
     for (const [sym, path] of Object.entries(defs)) {
       syms.add(sym)
       kinds.add(String(path))
@@ -116,6 +101,8 @@ function secretsBuild(model: Model, target: any): SecretsBuild | null {
     groups: groups.sort(),
     tlsGroups: tlsGroups.sort(),
     tls,
+    stubs: Array.from(stubs).sort(),
+    stubGroups: stubGroups.sort(),
     plugin: SECRETS_PLUGIN_MODULES,
     core: SECRETS_CORE_MODULES,
     helpers: [
@@ -144,28 +131,8 @@ const Config = cmp(async function Config(props: any) {
 
   const secrets = secretsBuild(model, target)
 
-  // 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.
-  // Passing target.name opts this target into the main slug/version/target
-  // identity fields (read by station's descriptor - see configDefinition).
   const { def: config } = configDefinition(model, target.name)
 
-  // `in` and `name` TRAVEL WITH THE PREFIX NOW. apidef resolved both from the
-  // spec's securityScheme all along and generation dropped them, so an
-  // apiKey-in-query API got an `authorization` header it does not read.
-  //
-  // Added to the shared `def` here rather than in configDefinition, so this
-  // change moves ocaml and nothing else - and both representations below
-  // render from the SAME object, which is why the JSON is stringified AFTER
-  // this rather than taken from configDefinition: the data rung and the
-  // literal rung must not be able to describe different configs.
-  //
-  // ONLY WHEN THEY DIFFER from the header/Authorization default, so every
-  // header-based SDK's sdk_config.ml is byte-identical to what it generated
-  // before. `options.auth` is absent entirely when auth is inactive
-  // (configDefinition's own gate), and there is nothing to qualify then.
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
   const authOpts = (config as any).options?.auth
@@ -183,16 +150,6 @@ const Config = cmp(async function Config(props: any) {
 
   File({ name: 'sdk_config.' + target.ext }, () => {
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // The literal is one nested expression the compiler type-checks as a
-    // single item; a string is one token, and `Sdk_json.json_read` builds the
-    // same value tree at runtime. That reader used to live only in the corpus
-    // test harness - this rung is why it now lives in the runtime, and the
-    // harness uses it from there rather than keeping a second copy.
-    //
-    // No number-type question: `json_read` yields `Num (float)` and
-    // `formatOcamlValue` emits `(Num (5.))`, so both branches agree.
     if (asData) {
       Content(`(* Generated API configuration (mirrors go core/config.go).
  *
@@ -231,15 +188,6 @@ let make_config () : value =
 `)
     }
 
-    // THE PLUGIN DEFINITIONS the model selected, per feature (the ocaml
-    // peer of Config_go's featurePlugins map). EMITTED UNCONDITIONALLY, so
-    // every generated config answers the same question - but typed as
-    // `Defs.definition list` only when the secrets feature is active: the
-    // `Defs` module is part of the vendored voxgig/plugin tree, which is
-    // compiled only then, so an inactive model gets the polymorphic empty
-    // list instead (`'a list`, which unifies with anything a caller
-    // expects). DELIBERATE DIVERGENCE from the c/lua accessors, whose
-    // untyped return (void**, a table) needs no such split.
     if (null == secrets) {
       Content(`
 (* The plugin definitions the model selected, per feature: none - no
@@ -259,16 +207,6 @@ let feature_plugins (name : string) : Defs.definition list =
   | _ -> []
 `)
 
-      // THE EXCHANGE TRANSPORT OF LAST RESORT (go's rawExchangeFetch): the
-      // vendored sekreto HTTP client, which the active plugin groups
-      // compile and link anyway (feature/secrets/feature.mk adds the OpenSSL binding on
-      // exactly this condition). It exists so an exchange works with
-      // ordinary SDK options - requiring a custom transport for the COMMON
-      // case would refuse every live token purchase before a request was
-      // made. Same result shape the system.fetch seam promises ({status,
-      // statusText, headers, body, json()}). With no such group the feature
-      // is built without it and a purchase with no options.system.fetch
-      // fails with a named error (see secrets_feature.ml).
       if (secrets.tls) {
         Content(`
 (* The token-exchange transport of last resort: the vendored sekreto HTTP
@@ -299,16 +237,10 @@ let make_feature (name : string) : feature =
   match name with
 `)
 
-    // ONLY THE FEATURES THIS PORT ACTUALLY IMPLEMENTS. Emitting an arm for a
-    // name with no `<name>_feature` in tm/ocaml/sdk_features.ml is an
-    // "Unbound value" at COMPILE time — the whole SDK fails to build, not
-    // just the feature. That is how the missing `cost` was found, when an SDK
-    // first activated every feature; cost is implemented now, and this list
-    // is the guard against the next one.
     const OCAML_FEATURES = [
       'audit', 'cache', 'clienttrack', 'cost', 'debug', 'idempotency', 'log',
       'metrics', 'netsim', 'paging', 'proxy', 'ratelimit', 'rbac',
-      'retry', 'streaming', 'telemetry', 'test', 'timeout',
+      'retry', 'streaming', 'telemetry', 'test', 'timeout', 'validate',
     ]
 
     each(feature, (f: any) => {
@@ -318,13 +250,6 @@ let make_feature (name : string) : feature =
       }
     })
 
-    // The secrets feature is the one ocaml feature that lives OUTSIDE
-    // sdk_features.ml (a container: feature/secrets_feature.ml plus the
-    // vendored trees), so its arm names its own module and hands it the
-    // definitions the model selected and, when a plugin group needing a
-    // transport is active, the bundled exchange transport. Emitted only
-    // when the feature is active: the module is not compiled otherwise
-    // (Main_ocaml's container gate, and the Makefile's feature/secrets/feature.mk).
     if (null != secrets) {
       Content(`  | "secrets" -> Secrets_feature.make ~plugins:(feature_plugins "secrets")${secrets.tls ? ' ~transport:secrets_transport' : ''} ()
 `)

package/project/.sdk/src/cmp/ocaml/EntityOperation_ocaml.ts

@@ -41,12 +41,6 @@ function entityOp(opname: string, present: boolean, entityname: string): string
     post = `            ()\n`
   }
 
-  // The op resolves to the ENTITY (see Sdk_types). `list` builds one entity
-  // per record here, since make_result works in `value` and cannot; `remove`
-  // marks the instance. With throwing disabled run_op returns the error
-  // payload, which an entity_obj return cannot carry, so that path resolves to
-  // the entity too and the caller reads ctrl.err - the mechanism no-throw mode
-  // documents anyway.
   const tail =
     'list' === opname
       ? `      let out = run_op ctx post_done in