@voxgig/sdkgen 4.20.0 → 4.22.0

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

@@ -36,30 +36,7 @@ import {
 } from './utility_rb'
 
 
-// PLUGIN DEFINITION REQUIRES AND THE FEATURE_PLUGINS MAP (the ruby peer of
-// cmp/py/Config_py.ts's pluginImports/pluginDefs).
-//
-// Upstream sekreto replaced its self-registration registry with
-// voxgig/plugin definitions: a provider kind the caller did not pass in via
-// `plugins: [...]` is unknown to that Sekreto. So config requires each
-// active plugin's module and names its exported definition CONSTANT (the
-// model's `def.rb` map), handing the list to the feature through
-// FEATURE_PLUGINS.
-//
-// The `def` map is declared in the model rather than derived from filenames
-// because one module may export several definitions (sekreto's aws.rb
-// exports AWSSECRETS and AWSPARAMS) - hence the de-duplication by path, so
-// a two-definition module yields ONE require. A def value is the module's
-// path under tm/rb, which is this target's root, so the require_relative is
-// that path without its extension.
-//
-// GATED, unlike go and py: the whole block is emitted only when an active
-// feature DECLARES a plugin catalogue for this target. An SDK that does not
-// carry the secrets feature must be byte-identical to what it was before
-// the feature existed, and an unread constant is not a thing a simple SDK
-// should have to explain.
 function rbPlugins(model: any, feature: any) {
-  // path -> [constant, ...], so one require serves a two-definition module.
   const bypath: Record<string, string[]> = {}
   const defs: Record<string, string[]> = {}
   let declared = false
@@ -111,24 +88,12 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Gated by the applicability tags, so this target never imports or
-  // registers a feature it has no source for. One rule, one place:
-  // helpers/applicability.
   const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
   const authPrefix = resolveAuthPrefix(model)
-  // `in` and `name` travel with the prefix now. They were resolved by
-  // apidef all along and dropped here, so an apiKey-in-query API got an
-  // `authorization` header it does not read. `basic` joins them because
-  // PrepareAuth_rb only emits its HTTP Basic branch for a basic scheme, and
-  // that branch reads this option at runtime.
-  //
-  // Each is emitted ONLY when it differs from the default, so an SDK with a
-  // plain header/Authorization bearer scheme regenerates byte-identical.
   const authBasic = isHttpBasicAuth(model)
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
@@ -155,13 +120,6 @@ const Config = cmp(async function Config(props: any) {
         },\n`
     : ''
 
-  // The same config as an OBJECT, built by the shared helper so this target's
-  // literal and the data that replaces it above the threshold are the same
-  // config by construction. The JSON is what the threshold is measured on -
-  // emitted source size varies by language, the model does not.
-  // Passing the target name opts in to the main slug/version/target identity
-  // fields (station descriptor inputs) - the literal path below emits them
-  // too, keeping data and literal reps in step.
   const { def: configDef, json: configJson } = configDefinition(model, target.name)
   const asData = isConfigData(configJson, configReprSetting(model))
 
@@ -170,9 +128,6 @@ const Config = cmp(async function Config(props: any) {
   const pluginRequireBlock = 0 === requires.length ? '' :
     '\n' + requires.join('\n') + '\n'
 
-  // Emitted whenever a catalogue is declared, even with every group off:
-  // the feature module reads the map unconditionally, and an SDK whose
-  // chain is all built-ins still has to answer with an empty list.
   const featurePluginsBlock = !declared ? '' :
     `  # The sekreto plugin DEFINITIONS the model selected per feature,
   # required above from the modules the catalogue's active \`plugin.def\`
@@ -205,17 +160,6 @@ ${featurePluginsBlock}  # Return the process-wide config, built once on first us
 
 `)
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // A hash literal makes the Ruby parser build a node per entry and the VM
-    // execute an instruction per entry on every load. A string constant is one
-    // token, and `JSON.parse` (a C extension) builds the hash far faster.
-    //
-    // `JSON.parse` yields exactly what the literal did - String keys, Integer
-    // for whole numbers, true/false/nil - so make_config's result is unchanged.
-    //
-    // A SINGLE-quoted literal, so the JSON survives verbatim: a double-quoted
-    // Ruby string would interpolate any `#{` the model happens to contain.
     if (asData) {
       Content(`  # THE API MODEL, EMBEDDED AS DATA (sdkgen rung L1).
   #

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

@@ -1,29 +1,5 @@
 
 
-// Typed-model generator (Ruby target).
-//
-// Ported from the TypeScript reference EntityTypes_ts.ts. Reads
-// main.<KIT>.entity.<e>.fields[] and per-op params (op.<name>.points[].args.params[])
-// and emits one file, <Sdk>_types.rb, containing a keyword-init Struct per active
-// entity plus a request/match Struct per active op. Ruby has no enforced static
-// types, so each member carries a YARD `@!attribute`/`@return` annotation whose
-// element type comes from the canonical sentinels via the shared sdkgen helper
-// `canonToType` (source of truth: @voxgig/apidef VALID_CANON):
-//   $STRING -> String, $INTEGER -> Integer, $NUMBER -> Float, $BOOLEAN -> Boolean,
-//   $OBJECT -> Hash, $ARRAY -> Array, unknown -> Object.
-//
-// Type-name scheme (as TS, with one Ruby-only guard): data type = <Name>,
-// except where Ruby core already owns that constant — `File`, `Time`, `Data`,
-// … — which would be silently REPLACED by the assignment; those become
-// <Name>Type (see rbSafeTypeName). Per-op request
-// <Name>LoadMatch / <Name>ListMatch / <Name>RemoveMatch (query/id ops),
-// <Name>CreateData / <Name>UpdateData (body ops). An op WITH params -> a Struct of
-// those params (reqd:false -> annotated `[Type, nil]`). An op WITHOUT params -> a
-// Struct over the entity fields (Struct members are always optional/nil, so this is
-// the Ruby stand-in for TS `Partial<Name>`; callers may equally pass a plain Hash).
-//
-// Struct.new(keyword_init: true) gives value objects usable as `Advice.new(id: ...)`.
-// The file is required by the main SDK module so these constants are always loaded.
 
 import {
   cmp, each, names,
@@ -47,17 +23,6 @@ function symName(name: string): string {
 }
 
 
-// Emit one typed value class: a YARD @!attribute block plus a keyword-init
-// Struct. Ruby's `Struct.new` rejects zero members, so an empty shape falls
-// back to a plain empty class (keeps the type name available).
-//
-// A member with an EMPTY name is dropped first. `Struct.new(:"")` raises
-// `NameError: cannot make operator ID : attrset` when the file loads, which
-// takes the whole SDK down rather than just that type -- and quoting does
-// not help, since the empty symbol is the one Ruby will not accept (`:"a-b"`
-// and `:"1x"` are both fine). A model should not carry a nameless field, so
-// upstream is where it gets fixed; this keeps one bad field from costing the
-// target everything.
 function emitStruct(
   typeName: string,
   doc: string,
@@ -92,24 +57,12 @@ function emitStruct(
 const EntityTypes = cmp(function EntityTypes(props: any) {
   const { model, log } = props.ctx$
 
-  // only_active:false — getModelPath DROPS active:false entries by default,
-  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
-  // collection, so inactive entities still get generated entity code that
-  // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  // Emit for EVERY entity that gets generated entity code: the consumer
-  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
-  // filter, so inactive entities still get class files referencing these
-  // typed names. Filter on `name` (always present), NOT `active` — parity
-  // with the go emitter's fix.
   const entityList = deriveEntityNames(entity)
   // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   File({ name: model.const.Name + '_types.' + LANG }, () => {
@@ -128,27 +81,16 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
     entityList.forEach((ent: any) => {
       const Name = ent.Name
-      // Ruby constants share ONE namespace with the core classes, and
-      // assigning one silently replaces it — an entity named `File` emitting
-      // `File = Struct.new(...)` clobbers ::File and every later `File.join`
-      // raises NoMethodError. Only the bare data-type constant needs the
-      // guard; the per-op names below always carry a suffix that no core
-      // constant matches. The `client.File(...)` accessor is a METHOD, a
-      // separate namespace, so the public surface is unchanged.
       const TypeName = rbSafeTypeName(Name)
       const fields = (ent.fields ? each(ent.fields) : [])
         .filter((f: any) => f.active !== false)
 
-      // Entity data model: one member per field (`req:false` -> nilable).
       emitStruct(
         TypeName,
         `${Name} entity data model.`,
         fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req })),
       )
 
-      // Per active op: a request/match Struct. Members and their optionality
-      // come from the shared partiality policy (opRequestShape); this file only
-      // renders them as a keyword-init Struct.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {

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

@@ -33,7 +33,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/rb/fragment/')
 
-  // Entity files go to entity/ folder
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.' + target.ext }, () => {
@@ -56,8 +55,6 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.rb so the class can be renamed independently.
           EntyClass: cls,
 
           // Feature-hook markers. jostraca's built-in `#Name-Tag` pattern is

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'
@@ -58,7 +59,6 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // Generate main SDK file
   File({ name: model.const.Name + '_sdk.' + target.ext }, () => {
 
     Fragment(
@@ -82,7 +82,6 @@ utility.feature_hook.call(@_rootctx, "${name}")
         }
       },
 
-      // Entities - injected at SLOT
       () => {
         each(entity, (entity: ModelEntity) => {
           const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -92,18 +91,11 @@ 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
-  // API, and tm/ can only hold one answer. See PrepareAuth_rb.
-  //
-  // At the TARGET ROOT, not inside the `.` folder above and not inside any
-  // `src`: rb's tree is flat (utility/, core/, feature/ sit at the root),
-  // the component opens the one `utility` folder it needs, and that
-  // reproduces tm/rb/utility/prepare_auth.rb's old path exactly.
   PrepareAuth({ target })
 
   // Generate typed models (<Sdk>_types.rb) — required by the main SDK file.

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

@@ -28,9 +28,6 @@ const Package = cmp(async function Package(props: any) {
   // constant here did.
   const author = authorInfo(model, target.name)
 
-  // Gem name is namespaced to model.origin (e.g. "voxgig-sdk"). RubyGems
-  // names can't contain "/", so the parts are hyphen-joined. The require
-  // path (`${model.name}_sdk`) is unchanged.
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const gemName = packageName(model, target.name)
@@ -39,7 +36,6 @@ const Package = cmp(async function Package(props: any) {
   const versionOf = (d: { version: string; source: 'feature' | 'target' }) =>
     d.source === 'target' ? (d.version || '0.0') : d.version
 
-  // Generate Gemfile
   File({ name: 'Gemfile' }, () => {
     Content(`source "https://rubygems.org"
 
@@ -53,7 +49,6 @@ gemspec
     }
   })
 
-  // Generate gemspec
   File({ name: model.const.Name + '_sdk.gemspec' }, () => {
     // RubyGems rejects a gemspec that declares the same runtime dependency
     // twice (Gem::InvalidSpecificationException at `gem build`), so the

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

@@ -16,28 +16,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated.
-//
-// This was a static file at `tm/rb/utility/prepare_auth.rb` that hardcoded
-// `HEADER_AUTH = "authorization"`. apidef has always resolved the scheme's
-// `in` and `name` into `main.kit.info.security` — joplin's says
-// `in: "query", name: "token"` — and generation dropped both. The result
-// was an SDK that sent a header the API does not read and never sent the
-// query parameter it does, so it could not authenticate at all. Four repos
-// in the cedar fleet shipped that way: joplin (`token`), pipedrive
-// (`api_token`), trello (`key`), lm-umbrella (`apiKey`).
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value that is fixed at
-// generation time.
-//
-// The ts port is the reference (cmp/ts/PrepareAuth_ts.ts). Two things are
-// deliberately NOT the same here, both recorded at their site below: the
-// header name is lower-cased, and the cookie clear removes our own pair
-// instead of a header that was never set.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -47,17 +25,6 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const name = resolveAuthName(model)
   const basic = isHttpBasicAuth(model)
 
-  // RB'S LAYOUT IS FLAT, WHICH IS WHY THIS FOLDER IS OPENED HERE AND THE TS
-  // PORT OPENS NONE. In ts, Main wraps its whole body in
-  // `Folder({name:'src'})` and the utilities live at `src/utility/`, so a
-  // second `src` there would write `src/src/utility/`. Main_rb opens no such
-  // folder: `Package`, `Gitignore`, the SDK file and `Copy({from:'tm/rb'})`
-  // all land at the target root, and `Config` sits inside a `Folder({name:
-  // '.'})` that is the root too. The template this replaces was
-  // `tm/rb/utility/prepare_auth.rb`, and that Copy's root IS the target root,
-  // so the file it produced was `<root>/utility/prepare_auth.rb`. One folder,
-  // `utility`, reproduces exactly that path — and register.rb's
-  // `require_relative 'prepare_auth'` (from `utility/`) only resolves there.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({ Name: model.const.Name, active, where, name, basic }))
@@ -101,22 +68,8 @@ end
   // mean something.
   const basicHere = spec.basic && 'header' === spec.where
 
-  // The constant keeps the template's name per placement, so a
-  // header-based SDK regenerates the file it already had.
   const CRED = query ? 'QUERY_AUTH' : cookie ? 'COOKIE_AUTH' : 'HEADER_AUTH'
 
-  // HEADER NAMES ARE LOWER-CASED; QUERY AND COOKIE NAMES ARE NOT.
-  //
-  // `resolveAuthName` answers 'Authorization' by default, but the whole rb
-  // runtime spells header names in lower case — the template's
-  // `HEADER_AUTH = "authorization"`, secrets_feature.rb's
-  // `headers["authorization"]`, debug_feature.rb's mask list. A Ruby Hash key
-  // is case-sensitive, so emitting "Authorization" here would leave the
-  // secrets feature writing a SECOND, separate header and the copied
-  // pipeline_test.rb assertions on `headers["authorization"]` failing. HTTP
-  // header names are case-insensitive on the wire, so lower-casing costs
-  // nothing. Query parameter and cookie names ARE case-sensitive (`?Token=`
-  // is not `?token=`), so those go in verbatim.
   const credName = query || cookie ? spec.name : spec.name.toLowerCase()
 
   const consts =
@@ -140,10 +93,6 @@ end
     : `    headers = spec.headers
 `
 
-  // Removing OUR pair, not the whole cookie header. The ts port deletes
-  // `headers[CRED_name]` for the cookie case, which is a header nothing ever
-  // set — so a stale cookie survives a withdrawn credential there. This
-  // splits the header, drops the one pair we own, and puts the rest back.
   const dropCookie = !cookie ? '' : `
     # Our own pair, and only ours: another cookie the caller set survives.
     drop_cookie = ->(hs) {
@@ -209,9 +158,6 @@ end
 // The one thing that actually differs between placements: where the
 // credential is written, and whether the prefix travels with it.
 function place(where: string, clear: string): string {
-  // NO PREFIX IN A QUERY STRING. `?token=Bearer%20abc` is not a thing any
-  // API reads; the prefix is a header convention and is dropped here
-  // deliberately rather than silently concatenated.
   if ('query' === where) {
     return `
     if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
@@ -244,7 +190,6 @@ function place(where: string, clear: string): string {
 `
   }
 
-  // HEADER: the template's body, unchanged.
   return `
     if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
       ${clear}
@@ -259,30 +204,6 @@ function place(where: string, clear: string): string {
 }
 
 
-// NOT `isAuthActive`, AND THE DIFFERENCE IS LOAD-BEARING (the py port found
-// this first; same reasoning, same fix).
-//
-// `isAuthActive` is false whenever the SPEC declares no security scheme
-// (`main.kit.info.auth: false`). That is a statement about the DEFINITION,
-// not a ban on ever sending a credential: apidef writes it for every spec
-// with no securitySchemes block, and those SDKs are still expected to honour
-// an `apikey` the caller passes. The template placed the credential
-// unconditionally, so they did.
-//
-// Gating the body on `isAuthActive` therefore does not trim dead code, it
-// deletes working authentication. MEASURED, not assumed: with the wider gate
-// this component emitted the no-op for generatedcompile's own fixture
-// (`main: kit: info: { ... auth: false }`) and two running rb lanes went red
-// —
-//
-//   rb: auth null beats an explicit apikey
-//     FAIL: baseline broken: an ordinary apikey was not sent
-//   rb: the secrets feature runs with the feature active
-//     expected the authorization header to carry OPTKEY01, got: nil
-//
-// So the no-op is emitted only when the PROJECT says so: `config.auth.active:
-// false`, an explicit per-SDK switch nobody sets by accident. A spec that is
-// merely silent keeps the credential path it has always had.
 function authSwitchedOn(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
@@ -290,8 +211,6 @@ function authSwitchedOn(model: any): boolean {
 }
 
 
-// A Ruby double-quoted literal. `#` is escaped only where it would OPEN an
-// interpolation, matching utility_rb.formatRubyValue.
 function rbstr(s: string): string {
   return '"' + String(s)
     .replace(/\\/g, '\\\\')

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

@@ -7,9 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct Ruby literal for a field's canonical type — the create body
-// is EXECUTED by the doc test, so it must carry a real value per field.
-// Strings render the quoted placeholder.
 function rbLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -54,7 +51,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
-    // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
     // Sanitise the local variable name — an entity whose lowercased name is a
     // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
@@ -111,9 +107,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
-      // The id key plus every REQUIRED match key (parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>

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

@@ -7,38 +7,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits test/readme_examples_test.rb — a Minitest COMPLETENESS GATE that
-// guarantees every fenced ruby code example in the package docs is unit-tested.
-// It reads ALL THREE docs — the root (multi-language) ../../README.md, the
-// Ruby-specific ../README.md, and ../REFERENCE.md — extracts every fenced ruby
-// block (tagged by source doc + index) and enforces four properties:
-//
-//   1. SYNTAX — `ruby -c` on every block. Every documented example must parse.
-//   2. RUN — every RUNNABLE block (one that constructs the SDK, drives
-//      client., or performs an entity op) is EXECUTED offline in seeded test
-//      mode against the real SDK. The captured stdout+stderr is scanned for
-//      FATAL programming-error markers REGARDLESS of exit code, so a bug that a
-//      documented begin/rescue swallows and prints is still caught. Only a
-//      not-found / domain error is tolerated.
-//   3. COMPLETENESS — every block is partitioned into exactly one of
-//      {executed, syntaxchecked-nonrunnable, illustration} and the counts must
-//      sum to the total. "illustration" is a NARROW explicit class (a
-//      signature / method-table block that names the SDK class or a documented
-//      method but never uses a live client) — never a catch-all. A
-//      runnable-looking block that was NOT executed lands in neither bucket and
-//      FAILS the gate: no runnable example can be silently skipped.
-//   4. A per-doc summary (total / executed / syntaxchecked / illustration) is
-//      printed.
-//
-// A runnable block is rewritten so its client is a test-mode client
-// (<Sdk>SDK.test) seeded with an in-memory fixture for every entity it
-// references; any real .new/.test constructor is rewritten and the doc's own
-// require of the SDK file is stripped (we require it by absolute path). A block
-// that only *uses* `client` (constructed in an earlier fenced block) gets a
-// test client prepended.
-//
-// The emitted Ruby builds the ``` fence via 96.chr and shells out via Open3,
-// so this generator string contains no backticks of its own.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { target } = props
   const { model } = props.ctx$

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/ReadmeHowto_rb.ts

@@ -8,7 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct Ruby literal for a field's canonical type.
 function rbLit(type: any): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -23,9 +22,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  // Pick an entity with a real op (prefer a read op) — never fabricate a
-  // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
-  // only when NO entity exposes any op (a direct()-only SDK).
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   // Sanitise the local variable name — an entity whose lowercased name is a
@@ -33,9 +29,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   // fixture KEY (`"${eName.toLowerCase()}"`) stays raw — it must match the
   // entity's registered name for the mock lookup to resolve.
   const eVar = exampleVarName(eName.toLowerCase(), 'rb')
-  // Model-driven id key: null when the entity has no id-like field (a
-  // response-wrapped spec). When null the fixture seeds no id and a match op
-  // takes no argument.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   const seedSentence = idF
@@ -44,8 +37,6 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const testCtor = idF
     ? `${model.const.Name}SDK.test({\n  "entity" => { "${eName.toLowerCase()}" => { "test01" => { "${idF}" => "test01" } } },\n})`
     : `${model.const.Name}SDK.test`
-  // A type-correct argument for the primary-op call: a match hash for load/
-  // remove, a required-field body for create/update, nothing for list.
   let testCallArg = ''
   if (exampleEntity && isMatchOp) {
     const items = opRequestShape(exampleEntity, primaryOp).items

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

@@ -47,12 +47,6 @@ client = ${ctor}
     // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
     const eVar = exampleVarName(eName.toLowerCase(), 'rb')
     const opnames = entityOps(exampleEntity)
-    // Model-driven id keys: `idF` is the load-MATCH key (null when the entity
-    // has no id-like field — a response-wrapped spec); when null, load/remove
-    // take no argument. `dataIdF` is the id on the RETURNED record's data type —
-    // an entity can key its match on an id it does not carry as data, so both a
-    // listed record's id column and a `created["id"]` read must be guarded on
-    // this, not the match key.
     const idF = entityIdField(exampleEntity)
     const dataIdF = entityDataIdField(exampleEntity)
 
@@ -136,9 +130,6 @@ end
 `)
     }
     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) =>
@@ -164,30 +155,18 @@ end
 `)
     }
 
-    // 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 Ruby-typed by the
-    // field's canonical type. 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) => (it.name !== idF && it.name !== 'id') ||
           ('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))
       return chosen.map((it: any) => `"${it.name}" => ${rbLit(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
-    // type-correct literal (so an update-without-create never references an
-    // undefined `created`).
     const idParamType = (opname: string): any => {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
@@ -216,8 +195,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/rb/ReadmeRef_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName , targetFeatures } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -55,7 +55,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)
 
@@ -197,7 +197,6 @@ ${eVar} = client.${ent.Name}
 `)
 
 
-      // Field schema
       if (fields.length > 0) {
         Content(`### Fields
 
@@ -244,7 +243,6 @@ ${eVar} = client.${ent.Name}
       }
 
 
-      // Operation details
       if (opnames.length > 0) {
         Content(`### Operations
 
@@ -260,7 +258,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
@@ -329,7 +326,6 @@ ${updateLines}  # Fields to update
       }
 
 
-      // Common methods
       Content(`### Common Methods
 
 #### \`data_get -> Hash\`
@@ -361,7 +357,6 @@ Return the entity name.
     })
 
 
-    // Features section
     const activeFeatures = each(feature).filter((f: any) => f.active)
     if (activeFeatures.length > 0) {
       Content(`
@@ -397,9 +392,6 @@ client = ${model.const.Name}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 })
     }