@voxgig/sdkgen 4.33.0 → 4.34.1

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 , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -29,8 +29,8 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   },
   list: {
     sig: 'list(reqmatch = nil, ctrl = nil) -> Array',
-    returns: 'Array',
-    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array. Raises on error.',
+    returns: 'Array of entities, one per record',
+    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array of entities, one per record; `data_get` reads each record. Raises on error.',
   },
   create: {
     sig: 'create(reqdata, ctrl = nil) -> result',
@@ -42,6 +42,11 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
     returns: 'result',
     desc: 'Update an existing entity. The data must include the entity `id`. Raises on error.',
   },
+  patch: {
+    sig: 'patch(reqdata, ctrl = nil) -> result',
+    returns: 'result',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Raises on error.',
+  },
   remove: {
     sig: 'remove(reqmatch, ctrl = nil) -> result',
     returns: 'result',
@@ -218,7 +223,7 @@ ${eVar} = client.${ent.Name}
         if (hasFieldOps) {
           // Only emit columns for operations this entity actually exposes —
           // never advertise a create/update/remove column the entity lacks.
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -258,6 +263,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           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
@@ -280,6 +289,7 @@ result = client.${ent.Name}.${opname}(${arg})
           else if ('list' === opname) {
             Content(`\`\`\`ruby
 results = client.${ent.Name}.list
+results.each { |item| puts item.data_get }
 \`\`\`
 
 `)
@@ -304,10 +314,10 @@ result = client.${ent.Name}.create({
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // The id key plus every REQUIRED data member — the same shape the
             // runtime validates — then the patch-fields note.
-            const updateItems = opRequestShape(ent, 'update').items
+            const updateItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
               .sort((a: any, b: any) =>
                 (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
@@ -315,13 +325,21 @@ result = client.${ent.Name}.create({
               `  "${it.name}" => ${rbLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ruby
-result = client.${ent.Name}.update({
-${updateLines}  # Fields to update
+result = client.${ent.Name}.${opname}({
+${updateLines}  # ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 })
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `String`, or an IO that responds to `read`',
+              once: 'an IO',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

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

@@ -52,9 +52,9 @@ client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`# List all ${eName.toLowerCase()}s (returns an Array; raises on error)
+      Content(`# List all ${eName.toLowerCase()}s (an Array of entities, one per record; raises on error)
 ${eVar}s = client.${eName}.list
-puts ${eVar}s
+${eVar}s.each { |item| puts item.data_get }
 `)
       hasCall = true
     }

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

@@ -45,7 +45,7 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
         ? `{ ${items.map((it: any) =>
           `"${it.name}" => ${it.name === idF ? '"test01"' : rbLit(it.type)}`).join(', ')} }`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => it.name !== idF && it.name !== 'id')
       const required = items.filter((it: any) => !it.optional)

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

@@ -249,7 +249,20 @@ class ${Name}CleanTest < Minitest::Test
     f.is_a?(Hash) && !f[name].nil?
   end
 
-  def make_sdk(scenario, sinks, cleanopts = nil, extra = [])
+  # Offline, as every generated suite is: the test OPTION resolves a required
+  # server variable to test-<name>, and installs no transport.
+  def offline(opts)
+    opts.merge("test" => { "active" => true })
+  end
+
+  # A client the sweep cannot build leaves nothing swept: a harness error, not a leak.
+  def construct(opts)
+    ${Name}SDK.new(offline(opts))
+  rescue StandardError => e
+    raise "clean harness: the client could not be constructed, so nothing was swept: #{e.message}"
+  end
+
+  def make_sdk(scenario, sinks, cleanopts = nil, extra = [], auth = nil)
     capture = ->(name) { ->(rec) { sinks.concat(Sweep.forms(name, rec)) } }
     feature = {}
     feature["log"] = { "active" => true, "logger" => CaptureLogger.new(sinks) } if has_feature?("log")
@@ -261,7 +274,7 @@ class ${Name}CleanTest < Minitest::Test
     feature["clienttrack"] = { "active" => true } if has_feature?("clienttrack")
 
     respond = scenario[1]
-    ${Name}SDK.new({
+    opts = {
       "apikey" => CANARY["apikey"],
       "secret" => CANARY["secret"],
       "headers" => { "X-Custom-Token" => CANARY["header"] },
@@ -269,7 +282,9 @@ class ${Name}CleanTest < Minitest::Test
       "feature" => feature,
       "extend" => [CaptureFeature.new(sinks)] + extra,
       "utility" => { "fetcher" => ->(_ctx, url, fetchdef) { respond.call(url, fetchdef) } },
-    })
+    }
+    opts["auth"] = auth unless auth.nil?
+    construct(opts)
   end
 
   # The first operation that completes against a plain 200: with no
@@ -277,7 +292,7 @@ class ${Name}CleanTest < Minitest::Test
   # An entity accessor is a capitalised client method whose result answers
   # get_name, as the feature corpus runner finds them.
   def usable_op
-    plain = ${Name}SDK.new({
+    plain = construct({
       "apikey" => CANARY["apikey"],
       "utility" => { "fetcher" => ->(_ctx, _url, _fd) { [Sweep.response(200, { "id" => "i1" }), nil] } },
     })
@@ -298,7 +313,7 @@ class ${Name}CleanTest < Minitest::Test
     entities = ${Name}Config.shared_config["entity"] || {}
     found.keys.sort.each do |entname|
       accessor = found[entname]
-      %w[list load create update remove].each do |op|
+      %w[list load create update patch remove].each do |op|
         next unless plain.public_send(accessor).respond_to?(op)
         filled = {}
         points = entities.dig(entname, "op", op, "points")
@@ -322,15 +337,18 @@ class ${Name}CleanTest < Minitest::Test
   def drive(sdk, target, ctrl, sinks)
     # A caller may keep the record it passed rather than read ctrl["explain"].
     held = ctrl["explain"]
+    entity = sdk.public_send(target["accessor"])
     out = nil
     err = nil
     begin
-      out = sdk.public_send(target["accessor"]).public_send(target["op"], target["match"].dup, ctrl)
+      out = entity.public_send(target["op"], target["match"].dup, ctrl)
     rescue StandardError => e
       err = e
     end
     sinks.concat(Sweep.forms("error", err)) unless err.nil?
     sinks.concat(Sweep.forms("result", out)) unless out.nil?
+    # Raw, as a caller copying the match into another query reads it.
+    sinks.concat(Sweep.forms("match", entity.match_get))
     sinks.concat(Sweep.forms("explain", ctrl["explain"])) unless ctrl["explain"].nil?
     sinks.concat(Sweep.forms("explain:held", held)) unless held.nil? || held.equal?(ctrl["explain"])
     err
@@ -356,11 +374,15 @@ class ${Name}CleanTest < Minitest::Test
       end
     end
 
+    # A name given at run time replaces the declared one: the match leaves
+    # out whichever name prepare_auth placed.
+    drive(make_sdk(SCENARIOS[0], sinks, nil, [], { "name" => "zzcred" }), target, {}, sinks)
+
     # A credential mistyped as a map is rejected by validation, whose
     # message quotes the value it rejected.
     rejected = nil
     begin
-      ${Name}SDK.new({ "apikey" => { "value" => CANARY["apikey"] }, "clean" => { "values" => CANARY["value"] } })
+      ${Name}SDK.new(offline({ "apikey" => { "value" => CANARY["apikey"] }, "clean" => { "values" => CANARY["value"] } }))
     rescue StandardError => e
       rejected = e
     end
@@ -432,7 +454,7 @@ class ${Name}CleanTest < Minitest::Test
     assert_equal({ "keys" => "zzsens", "values" => CANARY["config"] }, cfgclean)
 
     # With no clean option at all, the schema defaults still apply.
-    bare = ${Name}SDK.new({
+    bare = construct({
       "apikey" => CANARY["apikey"],
       "secret" => CANARY["secret"],
       "headers" => { "X-Custom-Token" => CANARY["header"] },
@@ -442,12 +464,14 @@ class ${Name}CleanTest < Minitest::Test
 
     # A feature's name is not a field name: only the sensitive names inside
     # its settings register. An entity block, of per-entity settings or
-    # seeded records keyed by entity name and id, is not read at all.
-    featured = ${Name}SDK.new({
+    # seeded records keyed by entity name and id, is not read at all, and nor
+    # are rbac's rules, keyed by entity and operation names.
+    featured = construct({
       "apikey" => CANARY["apikey"],
       "feature" => {
         "zzsecrets" => { "active" => false, "kind" => "PLAINSETTING-q8w2e4r6" },
         "zzfeat" => { "active" => false, "apitoken" => "FEATTOKEN-z9y8x7w6" },
+        "rbac" => { "active" => false, "rules" => { "zztoken.load" => "PLAINRULE-k7j5h3g1" } },
         "test" => { "active" => false, "entity" => {
           "zztoken" => { "ZZTOKEN01" => { "note" => "PLAINRECORD-t5r3e1w9" } } } },
       },
@@ -458,6 +482,7 @@ class ${Name}CleanTest < Minitest::Test
     ftoken = fclean.call(featured.get_root_ctx, "token FEATTOKEN-z9y8x7w6")
     frecord = fclean.call(featured.get_root_ctx, "record PLAINRECORD-t5r3e1w9")
     falias = fclean.call(featured.get_root_ctx, "alias PLAINALIAS-m2n4b6v8")
+    frule = fclean.call(featured.get_root_ctx, "rule PLAINRULE-k7j5h3g1")
 
     leaked = sinks
       .map { |s| [s["name"], Sweep.leaks(s["text"])] }
@@ -494,6 +519,7 @@ class ${Name}CleanTest < Minitest::Test
     assert_equal "token #{MASK}", ftoken
     assert_equal "record PLAINRECORD-t5r3e1w9", frecord
     assert_equal "alias PLAINALIAS-m2n4b6v8", falias
+    assert_equal "rule PLAINRULE-k7j5h3g1", frule
 
     explained = explains["ok/explain"] || {}
     refute_nil explained["result"], "the explain record should carry the result"

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

@@ -15,11 +15,26 @@ import {
   serverVarEnv,
   serverVariables,
   pointParts,
+  liveStrict,
+  liveStrictNote,
 } from '@voxgig/sdkgen'
 
 import { formatRubyValue } from './utility_rb'
 
 
+// Blocked without the ids its request needs, rather than sent with nil.
+function liveKeysBlock(keys: string[], entidEnvVar: string): string {
+  return 0 === keys.length ? '' : `    if setup[:live]
+      [${keys.map((k) => JSON.stringify(k)).join(', ')}].each do |_live_key|
+        if setup[:idmap][_live_key].nil?
+          Runner.live_miss(LIVE_STRICT, "Live test blocked: needs #{_live_key} via ${entidEnvVar}")
+        end
+      end
+    end
+`
+}
+
+
 function normalizePathParams(
   parts: string[],
   params: any[],
@@ -145,6 +160,10 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const entidEnvVar = `${PROJECTNAME}_TEST_${envToken(entity.name)}_ENTID`
 
+  // The *_ENTID key a live test reads a parameter's value from.
+  const liveKey = (param: any): string =>
+    ('id' === param.n ? entity.name : param.n.replace(/_id$/, '')) + '01'
+
   File({ name: entity.name + '_direct_test.' + target.ext }, () => {
 
     Content(`# ${entity.Name} direct test
@@ -155,25 +174,17 @@ require_relative "../${model.const.Name}_sdk"
 require_relative "runner"
 
 class ${entity.Name}DirectTest < Minitest::Test
+${liveStrictNote(liveStrict(model, target.name), '#', '  ')}
+  LIVE_STRICT = ${liveStrict(model, target.name)}
+
+  def live_ok(result)
+    status = Helpers.to_int(result["status"])
+    result["err"].nil? && result["ok"] && status >= 200 && status < 300
+  end
+
 `)
 
     if (hasList && listPoint) {
-      const listLiveIdKeys: string[] = listParams.map((lp: any) => {
-        return lp.n === 'id'
-          ? entity.name + '01'
-          : lp.n.replace(/_id$/, '') + '01'
-      })
-      const listSkipBlock = listLiveIdKeys.length > 0
-        ? `    if setup[:live]
-      [${listLiveIdKeys.map(k => `"${k}"`).join(', ')}].each do |_live_key|
-        if setup[:idmap][_live_key].nil?
-          skip "live test needs #{_live_key} via *_ENTID env var (synthetic IDs only)"
-          return
-        end
-      end
-    end
-`
-        : ''
       Content(`  def test_direct_list_${entity.name}
     setup = ${entity.name}_direct_setup([
       { "id" => "direct01" },
@@ -184,58 +195,28 @@ class ${entity.Name}DirectTest < Minitest::Test
       skip(_reason || "skipped via sdk-test-control.json")
       return
     end
-${listSkipBlock}    client = setup[:client]
+${liveKeysBlock(listParams.map(liveKey), entidEnvVar)}    client = setup[:client]
 
+    params = {}
 `)
-
-      if (listParams.length > 0) {
-        Content(`    params = {}
+      listParams.forEach((lp: any, i: number) => {
+        Content(`    params["${lp.n}"] = setup[:live] ? setup[:idmap]["${liveKey(lp)}"] : "direct0${i + 1}"
 `)
-        for (const lp of listParams) {
-          const key = lp.n === 'id'
-            ? entity.name + '01'
-            : lp.n.replace(/_id$/, '') + '01'
-          Content(`    if setup[:live]
-      params["${lp.n}"] = setup[:idmap]["${key}"]
-    else
-      params["${lp.n}"] = "direct01"
-    end
-`)
-        }
-        Content(`
+      })
+      Content(`
     result = client.direct({
       "path" => "${listPath}",
       "method" => "GET",
       "params" => params,
     })
-`)
-      } else {
-        Content(`
-    result = client.direct({
-      "path" => "${listPath}",
-      "method" => "GET",
-      "params" => {},
-    })
-`)
-      }
-
-      Content(`    if setup[:live]
-      # Live mode is lenient: synthetic IDs frequently 4xx and the list-
-      # response shape varies wildly across public APIs. Skip rather than
-      # fail when the call doesn't return a usable list.
-      if !result["err"].nil?
-        skip("list call failed (likely synthetic IDs against live API): #{result["err"]}")
-        return
-      end
-      unless result["ok"]
-        skip("list call not ok (likely synthetic IDs against live API)")
-        return
+    if setup[:live]
+      unless live_ok(result)
+        Runner.live_miss(LIVE_STRICT, "Live list failed: " + Runner.live_describe(result))
       end
-      status = Helpers.to_int(result["status"])
-      if status < 200 || status >= 300
-        skip("expected 2xx status, got #{status}")
-        return
+      if Runner.live_list(result["data"]).nil?
+        Runner.live_miss(LIVE_STRICT, "Live list returned no list: " + Runner.live_describe(result))
       end
+      assert Runner.live_list(result["data"]).is_a?(Array)
     else
       assert_nil result["err"]
       assert result["ok"]
@@ -250,13 +231,11 @@ ${listSkipBlock}    client = setup[:client]
     }
 
     if (hasLoad && loadPoint) {
-      const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
-        ? `    if setup[:live]
-      skip "live direct-load needs real ID — set *_ENTID env var with real IDs to run"
-      return
-    end
-`
-        : ''
+      const discover = !loadAllHaveExamples && hasList && 0 < loadParams.length
+      const idParam = loadParams.find((p: any) => 'id' === p.n)?.n ?? loadParams[0]?.n ?? 'id'
+      const loadLiveIdKeys: string[] = loadAllHaveExamples ? [] :
+        discover ? listParams.map(liveKey).concat(loadParams.filter((p: any) => idParam !== p.n).map(liveKey)) :
+          loadParams.map(liveKey)
       Content(`  def test_direct_load_${entity.name}
     setup = ${entity.name}_direct_setup({ "id" => "direct01" })
     _should_skip, _reason = Runner.is_control_skipped("direct", "direct-load-${entity.name}", setup[:live] ? "live" : "unit")
@@ -264,82 +243,71 @@ ${listSkipBlock}    client = setup[:client]
       skip(_reason || "skipped via sdk-test-control.json")
       return
     end
-${loadSkipBlock}    client = setup[:client]
+${liveKeysBlock([...new Set(loadLiveIdKeys)], entidEnvVar)}    client = setup[:client]
 
-`)
-
-      const needsQuery = loadParams.length > 0 || loadLiveQueryLines !== ''
-      if (needsQuery) {
-        Content(`    params = {}
+    params = {}
     query = {}
+    if setup[:live]
+${loadLiveQueryLines ? loadLiveQueryLines + '\n' : ''}`)
+      if (loadAllHaveExamples) {
+        Content(loadExampleLines + '\n')
+      }
+      else if (discover) {
+        Content(`      list_result = client.direct({
+        "path" => "${listPath}",
+        "method" => "GET",
+        "params" => {${listParams.map((p: any) => `"${p.n}" => setup[:idmap]["${liveKey(p)}"]`).join(', ')}},
+      })
+      unless live_ok(list_result)
+        Runner.live_miss(LIVE_STRICT, "Live list discovery failed: " + Runner.live_describe(list_result))
+      end
+      records = Runner.live_list(list_result["data"])
+      if records.nil?
+        Runner.live_miss(LIVE_STRICT, "Live list discovery returned no list: " + Runner.live_describe(list_result))
+      end
+      if records.empty?
+        Runner.live_empty("The account has no ${entity.name} record to load")
+      end
+      first = records[0].is_a?(Hash) ? records[0] : {}
+      found = first.fetch("${idParam}", first["id"])
+      if found.nil?
+        Runner.live_miss(LIVE_STRICT, "Live load blocked: discovery returned no usable identity")
+      end
+      params["${idParam}"] = found
 `)
-        if (loadAllHaveExamples) {
-          Content(`    if setup[:live]
-`)
-          if (loadLiveQueryLines) Content(loadLiveQueryLines + '\n')
-          Content(loadExampleLines + '\n')
-          Content(`    else
-`)
-          for (let i = 0; i < loadParams.length; i++) {
-            Content(`      params["${loadParams[i].n}"] = "direct0${i + 1}"
-`)
-          }
-          Content(`    end
-`)
-        } else if (loadParams.length > 0) {
-          if (loadLiveQueryLines) {
-            Content(`    if setup[:live]
-${loadLiveQueryLines}
-    end
+        for (const p of loadParams.filter((p: any) => idParam !== p.n)) {
+          Content(`      params["${p.n}"] = setup[:idmap]["${liveKey(p)}"]
 `)
-          }
-          Content(`    unless setup[:live]
-`)
-          for (let i = 0; i < loadParams.length; i++) {
-            Content(`      params["${loadParams[i].n}"] = "direct0${i + 1}"
+        }
+      }
+      else {
+        for (const p of loadParams) {
+          Content(`      params["${p.n}"] = setup[:idmap]["${liveKey(p)}"]
 `)
-          }
-          Content(`    end
+        }
+      }
+      Content(`    else
 `)
-        } else if (loadLiveQueryLines) {
-          Content(`    if setup[:live]
-${loadLiveQueryLines}
-    end
+      for (let i = 0; i < loadParams.length; i++) {
+        Content(`      params["${loadParams[i].n}"] = "direct0${i + 1}"
 `)
-        }
       }
+      Content(`    end
 
-      Content(`
     result = client.direct({
       "path" => "${loadPath}",
       "method" => "GET",
-`)
-      if (needsQuery) {
-        Content(`      "params" => params,
+      "params" => params,
       "query" => query,
-`)
-      } else {
-        Content(`      "params" => {},
-`)
-      }
-      Content(`    })
+    })
     if setup[:live]
-      # Live mode is lenient: synthetic IDs frequently 4xx. Skip rather
-      # than fail when the load endpoint isn't reachable with the IDs
-      # we can construct from setup.idmap.
-      if !result["err"].nil?
-        skip("load call failed (likely synthetic IDs against live API): #{result["err"]}")
-        return
+      unless live_ok(result)
+        Runner.live_miss(LIVE_STRICT, "Live load failed: " + Runner.live_describe(result))
       end
-      unless result["ok"]
-        skip("load call not ok (likely synthetic IDs against live API)")
-        return
-      end
-      status = Helpers.to_int(result["status"])
-      if status < 200 || status >= 300
-        skip("expected 2xx status, got #{status}")
-        return
+      if result["data"].nil?
+        Runner.live_miss(LIVE_STRICT, "Live load returned no data: " + Runner.live_describe(result))
       end
+      assert !result["data"].nil?
     else
       assert_nil result["err"]
       assert result["ok"]
@@ -376,11 +344,12 @@ def ${entity.name}_direct_setup(mockres)
     merged_opts = Runner.live_client_options.merge({${apikeyLiveField}${serverLiveField}
     })
     client = ${model.const.Name}SDK.new(merged_opts)
+    idmap = env["${entidEnvVar}"]
     return {
       client: client,
       calls: calls,
       live: true,
-      idmap: {},
+      idmap: idmap.is_a?(Hash) ? idmap : {},
     }
   end