@voxgig/sdkgen 4.2.8 → 4.3.0

package/project/.sdk/tm/js/test/feature/Corpus.test.js

@@ -0,0 +1,285 @@
+
+// Feature behaviour, driven by the SHARED corpus.
+//
+// This is the route PrimaryUtility.test.ts already takes for the utilities:
+// language-neutral cases in .sdk/test/test.json, executed against the REAL
+// generated SDK. Features here are ordinary classes in ordinary compiled
+// source, unit-tested the ordinary way — no transpiled templates, and no
+// miniature of the pipeline standing in for the pipeline (which is what
+// harness.ts does, and why its assertions can only be as right as the
+// miniature is). A feature is built through the generated config, wrapped
+// into a client built by the generated constructor, and driven by a real
+// entity operation. What is asserted is what ships.
+//
+// Everything in a case is data: features are activated by name, options are
+// plain JSON, the transport is scripted by `res`, and the assertion is a
+// subset of the client's own record. Turning `res` into a fetcher is the one
+// piece each language writes for itself.
+//
+// The ts twin of this file is the reference; keep the two in step.
+
+const { test, describe, before } = require('node:test')
+const { ok, deepStrictEqual } = require('node:assert')
+
+const { readFileSync } = require('node:fs')
+const { join } = require('node:path')
+
+const { SDK, TEST_JSON_FILE } = require('../utility/index')
+
+
+// Features with a corpus section. A name here with no section is a skip, not
+// a failure: an SDK generated without the feature has nothing to run.
+const FEATURES = ['cost']
+
+
+// One operation this SDK can actually perform is described by
+// { key, accessor, entity, op }: `key` is '<entity>.<op>', how features
+// attribute spend, and `accessor` is the client method returning the entity.
+
+
+// A scripted transport built from a case's `res` list. Responses are consumed
+// in order and the last one repeats, so a case that does not care how many
+// attempts happen need only declare one.
+function scriptedFetcher(res) {
+  let n = -1
+  return async function (_ctx, _url, _fetchdef) {
+    n++
+    const spec = res[n < res.length ? n : res.length - 1] || {}
+
+    if (true === spec.throw) {
+      throw new Error('scripted transport failure')
+    }
+
+    const headers = spec.headers || {}
+    const status = null == spec.status ? 200 : spec.status
+
+    return {
+      status,
+      statusText: status < 400 ? 'OK' : 'ERR',
+      body: 'not-used',
+      json: async () => (undefined === spec.body ? {} : spec.body),
+      headers: {
+        get(key) {
+          const lower = String(key).toLowerCase()
+          for (const k of Object.keys(headers)) {
+            if (k.toLowerCase() === lower) { return headers[k] }
+          }
+          return undefined
+        },
+        forEach(cb) { Object.keys(headers).forEach((k) => cb(headers[k], k, this)) },
+      },
+    }
+  }
+}
+
+
+function makeClient(kase) {
+  return new SDK({
+    feature: kase.feature,
+    utility: { fetcher: scriptedFetcher(kase.res || [{ status: 200, body: {} }]) },
+  })
+}
+
+
+// Every operation this SDK declares, in a stable order.
+//
+// The corpus cannot name an entity — it is shared by SDKs that have none in
+// common — so the runner finds them here. The generated client exposes one
+// capitalised, zero-argument accessor per entity, and the entity it returns
+// carries the same `name` the config is keyed by; that pairing is what turns
+// a config entry back into a callable method.
+function candidates(client) {
+  const entities = client._rootctx.config.entity || {}
+
+  const accessor = {}
+  for (const m of Object.getOwnPropertyNames(Object.getPrototypeOf(client))) {
+    if (!/^[A-Z]/.test(m) || 'function' !== typeof client[m]) { continue }
+    let inst
+    try { inst = client[m]() }
+    catch (e) { continue }
+    if (null != inst && 'string' === typeof inst.name && null != entities[inst.name]) {
+      accessor[inst.name] = m
+    }
+  }
+
+  const out = []
+  for (const entity of Object.keys(entities).sort()) {
+    if (null == accessor[entity]) { continue }
+    for (const op of Object.keys(entities[entity].op || {}).sort()) {
+      out.push({ key: entity + '.' + op, accessor: accessor[entity], entity, op })
+    }
+  }
+  return out
+}
+
+
+// Pick operations the corpus can drive, by DRIVING them: an op is usable when
+// it completes against a plain 200 with no feature active. Declared ops are
+// not all callable with no arguments (a required path parameter, a body), and
+// a case that failed for that reason would look like a feature defect.
+async function usableOps(want) {
+  const picked = []
+  for (const cand of candidates(makeClient({}))) {
+    const client = makeClient({})
+    try {
+      await client[cand.accessor]()[cand.op]({}, {})
+    }
+    catch (e) { continue }
+    picked.push(cand)
+    if (want <= picked.length) { break }
+  }
+  return picked
+}
+
+
+// Replace #OP1/#OP2 throughout a case, keys included.
+function resolve(node, tokens) {
+  if ('string' === typeof node) {
+    let s = node
+    for (const t of Object.keys(tokens)) { s = s.split(t).join(tokens[t]) }
+    return s
+  }
+  if (Array.isArray(node)) {
+    return node.map((n) => resolve(n, tokens))
+  }
+  if (null != node && 'object' === typeof node) {
+    const out = {}
+    for (const k of Object.keys(node)) {
+      out[resolve(k, tokens)] = resolve(node[k], tokens)
+    }
+    return out
+  }
+  return node
+}
+
+
+// Which #OPn tokens a case uses. A case wanting more operations than this SDK
+// has is skipped rather than failed.
+function tokensUsed(kase) {
+  const m = JSON.stringify(kase).match(/#OP(\d+)/g) || []
+  return m.reduce((max, t) => Math.max(max, Number(t.slice(3))), 0)
+}
+
+
+// Assert that `actual` contains `expect`, recursively. Cases assert only the
+// fields they are about, so a full deepStrictEqual would force every case to
+// restate the whole record.
+function subset(actual, expect, path) {
+  if (null != expect && 'object' === typeof expect && !Array.isArray(expect)) {
+    for (const k of Object.keys(expect)) {
+      ok(null != actual, `${path}.${k}: nothing at ${path}`)
+      subset(actual[k], expect[k], `${path}.${k}`)
+    }
+    return
+  }
+  deepStrictEqual(actual, expect, path)
+}
+
+
+describe('FeatureCorpus', () => {
+
+  let corpus
+  let ops = []
+  let byKey = {}
+
+
+  before(async () => {
+    corpus = JSON.parse(readFileSync(join(__dirname, '..', TEST_JSON_FILE), 'utf8'))
+    ops = await usableOps(2)
+    byKey = {}
+    for (const o of ops) { byKey[o.key] = o }
+  })
+
+
+  // A corpus with no `feature` section is a SKIP, not a failure.
+  //
+  // Each project carries its OWN materialised copy of .sdk/test/test.json, so
+  // a project scaffolded before the section existed legitimately has no cases
+  // to run - and a hard assertion here turned that into a red suite in every
+  // SDK on the fleet, for a corpus the project had simply not re-pulled yet.
+  //
+  // The strict check belongs where the corpus is CONTROLLED, not where it is
+  // consumed: sdkgen's own end-to-end lane generates against a corpus it
+  // supplies and requires the cases to actually run, so a section that goes
+  // missing there still fails loudly.
+  test('the corpus carries a feature section', (t) => {
+    if (null == corpus.feature) {
+      return t.skip(
+        'this project\'s test.json has no `feature` section - recompile the ' +
+        'corpus (create-sdkgen .sdk/test/feature/) to run these cases')
+    }
+  })
+
+
+  // At least one operation, or every case below would skip and the whole
+  // suite would report green having run nothing.
+  test('this SDK has an operation the corpus can drive', () => {
+    ok(0 < ops.length,
+      'no declared operation completed against a plain 200 — the corpus ' +
+      'cannot exercise a feature without one')
+  })
+
+
+  for (const name of FEATURES) {
+
+    test(name, async (t) => {
+      const section = corpus.feature?.[name]
+      if (null == section) {
+        return t.skip(`no corpus section for ${name}`)
+      }
+
+      const probe = makeClient({})
+      if (!probe._rootctx.config.hasFeature(name)) {
+        return t.skip(`this SDK was generated without the ${name} feature`)
+      }
+
+      const cases = section.basic?.set || []
+      ok(0 < cases.length,
+        `corpus section feature.${name} ran ZERO cases — a renamed section ` +
+        `or an emptied fixture must fail loudly, not pass silently`)
+
+      let ran = 0
+      for (const raw of cases) {
+        const need = tokensUsed(raw)
+        if (ops.length < need) {
+          t.diagnostic(`skip "${raw.name}": needs ${need} operations, this SDK offers ${ops.length}`)
+          continue
+        }
+
+        const tokens = {}
+        for (let i = 0; i < need; i++) { tokens['#OP' + (i + 1)] = ops[i].key }
+
+        const kase = resolve(raw, tokens)
+        const client = makeClient(kase)
+
+        for (const step of (kase.op || [])) {
+          const ref = byKey[step.op]
+          ok(null != ref, `${kase.name}: no operation ${step.op}`)
+          try {
+            await client[ref.accessor]()[ref.op]({}, step.ctrl || {})
+            ok(null == step.err,
+              `${kase.name}: ${step.op} was expected to fail, and did not`)
+          }
+          catch (err) {
+            if (null == step.err) { throw err }
+            if ('string' === typeof step.err) {
+              deepStrictEqual(err.code, step.err, `${kase.name}: wrong error code`)
+            }
+          }
+        }
+
+        subset(client[`_${name}`], kase.out, `${kase.name}: _${name}`)
+        ran++
+      }
+
+      ok(0 < ran, `every feature.${name} case was skipped`)
+      // Say how many ran. A partial run is legitimate (an SDK with one
+      // operation skips the cases needing two) but it should be visible
+      // rather than inferred from a green tick - and it is the one line
+      // sdkgen's end-to-end lane reads, in the same wording, from every
+      // language's runner.
+      t.diagnostic(`feature.${name}: ran ${ran} of ${cases.length} ` +
+        `case(s) against ${ops.length} operation(s)`)
+    })
+  }
+})

package/project/.sdk/tm/perl/t/feature_corpus.t

@@ -0,0 +1,345 @@
+#!perl
+# ProjectName SDK feature corpus test
+#
+# Feature behaviour, driven by the SHARED corpus.
+#
+# The same route t/primary_utility.t takes for the utilities: language-neutral
+# cases in .sdk/test/test.json, executed against THIS generated SDK. The
+# feature is the ordinary package, built by the generated config, installed by
+# the generated constructor, and driven by a real entity operation. Not a
+# miniature of the pipeline, which can only be as right as the miniature.
+#
+# Everything in a case is data. The one piece perl writes for itself is
+# turning scripted responses into a fetcher, through the documented
+# `utility.fetcher` override.
+
+use strict;
+use warnings;
+use Test::More;
+use FindBin;
+use lib "$FindBin::Bin/../lib";
+use Cwd ();
+use Scalar::Util ();
+
+use ProjectNameSDK;
+
+my $TEST_JSON = Cwd::abs_path("$FindBin::Bin/../../.sdk/test/test.json");
+
+unless (defined $TEST_JSON && -e $TEST_JSON) {
+  plan skip_all => 'test.json corpus not found';
+}
+
+# Features with a corpus section. A name here with no section is a skip, not
+# a failure: an SDK generated without the feature has nothing to run.
+my @FEATURE_CORPUS_NAMES = ('cost');
+
+# The standard operation names, in the order the runner prefers them.
+my @FEATURE_CORPUS_OPS = qw(load list create update remove);
+
+my $CORPUS = do {
+  open my $fh, '<', $TEST_JSON or die "cannot read $TEST_JSON: $!";
+  local $/;
+  my $raw = <$fh>;
+  close $fh;
+  Voxgig::Struct::parse_json($raw);
+};
+
+# A corpus with no `feature` section is a SKIP, not a failure. Each
+# project carries its OWN materialised copy of .sdk/test/test.json, so a
+# project scaffolded before the section existed legitimately has no cases
+# to run - and a hard assertion here turned that into a red suite in every
+# SDK on the fleet, for a corpus the project had simply not re-pulled yet.
+# The strict check belongs where the corpus is CONTROLLED: sdkgen's own
+# end-to-end lane supplies one and requires the cases to actually run.
+unless (defined $CORPUS->{feature}) {
+  plan skip_all => "this project's test.json has no `feature` section - "
+    . 'recompile the corpus (create-sdkgen .sdk/test/feature/) to run these cases';
+}
+ok(defined $CORPUS->{feature}, 'the corpus carries a feature section');
+
+
+# A scripted transport built from a case's `res` list. Responses are consumed
+# in order and the last one repeats, so a case that does not care how many
+# attempts happen need only declare one.
+#
+# Returns the shape the real fetcher returns: a (response, err) PAIR, with the
+# parsed body behind a `json` coderef and `body` as the raw string. A script
+# that only set `body` would look like an empty result, which reads as a
+# feature defect rather than a mis-shaped script.
+sub scripted_fetcher {
+  my ($res) = @_;
+  my $n = -1;
+  return sub {
+    my ($ctx, $fullurl, $fetchdef) = @_;
+    $n++;
+    my $spec = {};
+    if (ref $res eq 'ARRAY' && @$res) {
+      my $i = $n >= scalar(@$res) ? scalar(@$res) - 1 : $n;
+      $spec = $res->[$i] || {};
+    }
+
+    if (($spec->{throw} || 0) eq '1' || (defined $spec->{throw} && $spec->{throw})) {
+      return (undef, 'scripted transport failure');
+    }
+
+    my $status = defined $spec->{status} ? int($spec->{status}) : 200;
+    my $body = defined $spec->{body} ? $spec->{body} : {};
+
+    return ({
+      'status'     => $status,
+      'statusText' => ($status < 400 ? 'OK' : 'ERR'),
+      'headers'    => { %{ $spec->{headers} || {} } },
+      'json'       => sub { $body },
+      'body'       => Voxgig::Struct::stringify($body),
+    }, undef);
+  };
+}
+
+
+# Build a client the way a caller would.
+#
+# The plain constructor, not the test-mode one: the `test` feature is
+# transport: 'base' and REPLACES the transport, so a client in test mode
+# would shadow the script.
+sub build_client {
+  my ($kase) = @_;
+  my $opts = { 'utility' => { 'fetcher' => scripted_fetcher($kase->{res}) } };
+  $opts->{feature} = $kase->{feature} if defined $kase->{feature};
+  return ProjectNameSDK->new($opts);
+}
+
+
+# Every operation this SDK declares, in a stable order.
+#
+# The corpus cannot name an entity - it is shared by SDKs with none in common
+# - so the runner finds them here. An entity accessor is a capitalised client
+# method whose result answers get_name.
+sub candidates {
+  my ($client) = @_;
+  my %found;
+
+  my $pkg = ref $client;
+  no strict 'refs';
+  for my $sym (sort keys %{"${pkg}::"}) {
+    next unless $sym =~ /^[A-Z]/;
+    next unless defined &{"${pkg}::${sym}"};
+    my $ent = eval { $client->$sym() };
+    next unless defined $ent && Scalar::Util::blessed($ent);
+    next unless $ent->can('get_name');
+    my $entname = eval { $ent->get_name };
+    next unless defined $entname && length $entname;
+    $found{$entname} = [$sym, $ent];
+  }
+  use strict 'refs';
+
+  my @out;
+  for my $entname (sort keys %found) {
+    my ($accessor, $ent) = @{ $found{$entname} };
+    for my $opname (@FEATURE_CORPUS_OPS) {
+      next unless $ent->can($opname);
+      push @out, {
+        key      => "$entname.$opname",
+        accessor => $accessor,
+        op       => $opname,
+      };
+    }
+  }
+  return @out;
+}
+
+
+sub invoke {
+  my ($client, $op, $ctrl) = @_;
+  my $acc = $op->{accessor};
+  my $fn  = $op->{op};
+  my $ent = $client->$acc();
+  return $ent->$fn({}, $ctrl);
+}
+
+
+# Pick operations by DRIVING them: an op is usable when it completes against a
+# plain 200 with no feature active. Declared operations are not all callable
+# with no arguments, and a case failing for that reason would read as a
+# feature defect.
+sub usable_ops {
+  my ($want) = @_;
+  my @picked;
+  for my $cand (candidates(build_client({}))) {
+    my $ok = eval { invoke(build_client({}), $cand, {}); 1 };
+    next unless $ok;
+    push @picked, $cand;
+    last if scalar(@picked) >= $want;
+  }
+  return @picked;
+}
+
+
+# Replace #OPn throughout a case, keys included.
+sub resolve {
+  my ($node, $tokens) = @_;
+  if (ref $node eq 'ARRAY') {
+    return [ map { resolve($_, $tokens) } @$node ];
+  }
+  if (ref $node eq 'HASH') {
+    my %out;
+    for my $k (keys %$node) {
+      $out{ resolve($k, $tokens) } = resolve($node->{$k}, $tokens);
+    }
+    return \%out;
+  }
+  if (!ref $node && defined $node) {
+    my $out = $node;
+    for my $tok (keys %$tokens) {
+      my $q = quotemeta $tok;
+      $out =~ s/$q/$tokens->{$tok}/g;
+    }
+    return $out;
+  }
+  return $node;
+}
+
+
+# The highest #OPn a case mentions.
+sub tokens_used {
+  my ($kase) = @_;
+  my $json = Voxgig::Struct::stringify($kase);
+  my $max = 0;
+  while ($json =~ /#OP(\d+)/g) {
+    $max = $1 if $1 > $max;
+  }
+  return $max;
+}
+
+
+sub member {
+  my ($actual, $key) = @_;
+  return (undef, 0) unless defined $actual;
+  if (ref $actual eq 'HASH' || Scalar::Util::blessed($actual)) {
+    return ($actual->{$key}, 1) if exists $actual->{$key};
+  }
+  return (undef, 0);
+}
+
+
+# Assert that `actual` contains `expect`, recursively. Cases assert only the
+# fields they are about, so a full deep comparison would force every case to
+# restate the whole record.
+sub subset {
+  my ($actual, $expect, $path) = @_;
+
+  if (ref $expect eq 'HASH') {
+    for my $k (sort keys %$expect) {
+      my ($got, $found) = member($actual, $k);
+      ok($found, "$path.$k exists") or next;
+      subset($got, $expect->{$k}, "$path.$k");
+    }
+    return;
+  }
+
+  # JSON true/false parse to a blessed Voxgig::Struct::Bool, and perl's own
+  # booleans are a bare 1 or ''. Compare truth, not spelling: stringified,
+  # those two are 'true' and '1' and would never match.
+  if (Voxgig::Struct::is_jbool($expect)) {
+    is(($actual ? 1 : 0), ($expect ? 1 : 0), "$path is $expect");
+    return;
+  }
+
+  if (!ref $expect && defined $expect && Scalar::Util::looks_like_number($expect)) {
+    ok(!ref $actual && defined $actual && Scalar::Util::looks_like_number($actual),
+      "$path is a number") or return;
+    # Money is float arithmetic; compare with a tolerance far below any amount
+    # a case states.
+    ok(abs($actual - $expect) < 1e-9, "$path == $expect (got "
+      . (defined $actual ? $actual : 'undef') . ')');
+    return;
+  }
+
+  is($actual, $expect, $path);
+}
+
+
+sub record {
+  my ($client, $name) = @_;
+  return $client->{"_$name"};
+}
+
+
+my @ops = usable_ops(2);
+
+# At least one operation, or every case would skip and this file would report
+# green having run nothing.
+ok(scalar(@ops) > 0,
+  'this SDK has an operation the corpus can drive') or do {
+  done_testing();
+  exit 0;
+};
+
+for my $name (@FEATURE_CORPUS_NAMES) {
+  my $section = ($CORPUS->{feature} || {})->{$name};
+  next unless defined $section;
+
+  my $cases = (($section->{basic} || {})->{set}) || [];
+  ok(scalar(@$cases) > 0,
+    "corpus section feature.$name has cases (an emptied fixture must fail loudly)")
+    or next;
+
+  # Probed by ACTIVATING it: the feature defaults to inactive, so an idle
+  # client never builds it and its absence says nothing.
+  my $probe = build_client({ feature => [ { name => $name, active => 1 } ] });
+  next unless defined record($probe, $name);
+
+  my %by_key = map { $_->{key} => $_ } @ops;
+
+  my $ran = 0;
+  for my $raw (@$cases) {
+    my $need = tokens_used($raw);
+    next if $need > scalar(@ops);
+
+    my %tokens;
+    for my $i (0 .. $need - 1) {
+      $tokens{ '#OP' . ($i + 1) } = $ops[$i]{key};
+    }
+    my $kase = resolve($raw, \%tokens);
+
+    my $client = build_client($kase);
+    my $label = $kase->{name} || '';
+
+    for my $step (@{ $kase->{op} || [] }) {
+      my $op = $by_key{ $step->{op} };
+      ok(defined $op, "$label: operation $step->{op} is known") or next;
+      my $ctrl = $step->{ctrl} || {};
+      my $wanterr = $step->{err};
+
+      my $ok = eval { invoke($client, $op, $ctrl); 1 };
+      my $err = $@;
+
+      if (!defined $wanterr) {
+        ok($ok, "$label: $step->{op} succeeded")
+          or diag("failed unexpectedly: $err");
+        next;
+      }
+
+      ok(!$ok, "$label: $step->{op} failed as expected") or next;
+
+      if (!ref $wanterr) {
+        # The CODE, not the message: make_error prefixes and humanises the
+        # text, so matching it would pass on any error mentioning the word.
+        my $code = (Scalar::Util::blessed($err) && $err->can('code'))
+          ? $err->code : undef;
+        is($code, $wanterr, "$label: error code");
+      }
+    }
+
+    subset(record($client, $name), $kase->{out}, "$label: _$name");
+    $ran++;
+  }
+
+  ok($ran > 0, "at least one feature.$name case ran");
+  # Say how many ran. A partial run is legitimate (an SDK with one operation
+  # skips the cases needing two) but it should be visible rather than
+  # inferred from a green tick.
+  diag(sprintf('feature.%s: ran %d of %d case(s) against %d operation(s)',
+    $name, $ran, scalar(@$cases), scalar(@ops)));
+}
+
+done_testing();

package/project/.sdk/tm/perl/utility/make_options.pm

@@ -19,10 +19,42 @@ $REGISTRY{make_options} = sub {
   my ($ctx) = @_;
   my $options = $ctx->{options} || {};
 
+  # Merge custom utility overrides.
+  #
+  # A key naming a real utility member REPLACES it; anything else is attached
+  # as a custom extra. This mirrors ts, where the utility is an open object
+  # and one setprop does both.
+  #
+  # Without the replace half this was a no-op: every entry went to
+  # `{utility}{custom}`, which nothing reads, so a caller passing
+  # `utility => { fetcher => $my_transport }` - the documented way to script
+  # the transport, and the seam the shared feature corpus runs on - was
+  # silently ignored while ts and js honoured it.
+  #
+  # Option keys are camelCase, as ts spells them; members here are
+  # snake_case. Converting rather than listing keeps the mapping to one rule,
+  # so a utility added later is overridable without touching this. The
+  # registrar has already populated every member, so `exists` is the test for
+  # "is this a real one" - once the key is known to be a PUBLIC name.
   my $custom_utils = ProjectNameHelpers::gp($options, 'utility');
   if (Voxgig::Struct::ismap($custom_utils) && $ctx->{utility}) {
+    my $utility = $ctx->{utility};
     for my $k (keys %$custom_utils) {
-      $ctx->{utility}{custom}{$k} = $custom_utils->{$k};
+      # Public utility names are camelCase and carry no underscore, so an
+      # underscore means the caller named something of their own - possibly
+      # the INTERNAL spelling of a real member. `make_error` must stay an
+      # extension in `custom`; replacing the pipeline function with it (ts,
+      # js and go all keep it) would break the error path on the next
+      # request, silently.
+      my $public_name = ($k !~ /_/);
+      my $member = $k;
+      $member =~ s/([A-Z])/'_' . lc($1)/ge;
+      if ($public_name && 'custom' ne $member && exists $utility->{$member}) {
+        $utility->{$member} = $custom_utils->{$k};
+      }
+      else {
+        $utility->{custom}{$k} = $custom_utils->{$k};
+      }
     }
   }
 

package/project/.sdk/tm/php/core/Context.php

@@ -52,6 +52,9 @@ class ProjectNameContext
             if (isset($ctrl_raw['explain']) && is_array($ctrl_raw['explain'])) {
                 $this->ctrl->explain = $ctrl_raw['explain'];
             }
+            if (array_key_exists('actor', $ctrl_raw)) {
+                $this->ctrl->actor = $ctrl_raw['actor'];
+            }
         } elseif ($basectx !== null && $basectx->ctrl !== null) {
             $this->ctrl = $basectx->ctrl;
         }