@voxgig/create-sdkgen 0.23.0 → 0.25.0

package/project/standard/.sdk/src/Root.ts

@@ -45,7 +45,6 @@ const Root = cmp(function Root(props: any) {
   ctx$.util = ctx$.util || {}
   ctx$.util.makeFlow = makeFlow
 
-  // TODO: move to @voxgig/util as duplicated
   model.const = { name: model.name }
   names(model.const, model.name)
   model.const.year = new Date().getFullYear()
@@ -65,16 +64,13 @@ const Root = cmp(function Root(props: any) {
   })
 
   names(model, model.name)
-  // console.log('MODEL name', model.name, model.Name)
 
   // Standard Replacements
   ctx$.stdrep = {}
   names(ctx$.stdrep, model.Name, 'Project' + 'Name')
-  // console.log('STDREP', stdrep)
 
   Project({}, () => {
 
-    // TODO: jostraca should accept no props
     Top({})
 
     BuildSDK({})
@@ -84,22 +80,6 @@ const Root = cmp(function Root(props: any) {
 
       Folder({ name: target.name }, () => {
 
-        // Per-generation-phase activation. A target's aontu model carries
-        // a `phase` map mirroring the feature pattern:
-        //
-        //   phase: {
-        //     entity:     { active: false }
-        //     feature:    { active: false }
-        //     readme:     { active: false }
-        //     agentguide: { active: false }
-        //     test:       { active: false }
-        //   }
-        //
-        // Defaults are inclusive — when a phase entry is absent (or
-        // active is not explicitly false), the phase runs. Existing
-        // standard targets don't declare `phase` and keep current
-        // behaviour. A CLI-style target switches all five off and
-        // only emits Main.
         const phase = target.phase || {}
         const phaseActive = (name: string): boolean =>
           false !== (phase[name] && phase[name].active)
@@ -145,7 +125,6 @@ function makeFlow(def: any, data: any, stepMakers: Record<string, any>) {
 
   const steps: any = {}
   each(stepMakers, (n: any) => {
-    // TODO: support after?
     if ('function' === typeof n.val$) {
       steps[n.key$] = (id: any, pdef: any) => makeFlowStep(id(), pdef, n.val$)
     }
@@ -210,7 +189,6 @@ function makeFlow(def: any, data: any, stepMakers: Record<string, any>) {
     names(step, step.entity, 'entity')
   })
 
-  // console.log('STEPS', stepMakers, steps, def)
 
   const spec = transform(def, {
     p: ['`$EACH`', 'step', {

package/project/standard/.sdk/src/Top.ts

@@ -20,9 +20,6 @@ const Top = cmp(function Top(props: any) {
   // any target Folder (same placement rule as ReadmeTop / Deploy).
   AgentGuideTop({})
 
-  // Root governance files for a publishable, unofficial generated SDK:
-  // an MIT LICENSE (held by Voxgig), a SECURITY.md disclosure policy, and a
-  // seed CHANGELOG. Emitted at repo root, before the per-target folders.
   License({})
   Security({})
   Changelog({})
@@ -32,11 +29,6 @@ const Top = cmp(function Top(props: any) {
   // `make deploy-dry` rehearsal.
   Deploy({})
 
-  // Publishing an npm target from CI with no token: a dispatch workflow per
-  // npm target using GitHub OIDC trusted publishing, and the one-time
-  // set-up a maintainer must do, written to `.sdk/PUBLISHING.md` — beside
-  // the generator rather than into the target's own docs, which describe
-  // the SDK to the people who install it.
   PublishWorkflow({})
 })
 

package/project/standard/.sdk/test/feature/cost.aon

@@ -1,38 +1,3 @@
-# Cost feature behaviour, as language-neutral cases.
-#
-# Every case is DATA: features are activated by name through the generated
-# config, the options are plain JSON, the transport is scripted by `res`, and
-# the assertion is a subset of the client's cost record. Nothing here needs a
-# function, which is what makes it corpus-expressible where featureAdd /
-# featureHook / featureInit are not (see their PENDING notes).
-#
-# CASE SHAPE
-#   name     label for the runner
-#   feature  activation list, IN ORDER. The array form is the one that fixes
-#            nesting: each transport feature wraps whatever is already
-#            installed, so position IS order. Entries are flat -
-#            { name, active, ...options } - as makeOptions expects.
-#   res      scripted transport responses, consumed in order; the last is
-#            reused once exhausted. `throw: true` makes that attempt reject
-#            at the transport rather than return a response.
-#   op       operations to run, in order. `err` marks an op that must FAIL:
-#            `true` for any failure, a string to pin the error code.
-#   out      expected SUBSET of client._cost - runners match partially, so a
-#            case asserts only what it is about
-#
-# OPERATION TOKENS
-#   The corpus is shared by every generated SDK, and each has its own
-#   entities and operations, so no case may name one. `#OP1` and `#OP2` stand
-#   for two DISTINCT operations this SDK can actually perform; the runner
-#   discovers them from the generated client and substitutes them throughout
-#   the case, keys included. They resolve to the '<entity>.<op>' key the cost
-#   record attributes spend under, which is why a rate table can be keyed on
-#   one. A SDK that offers fewer operations than a case needs skips that case
-#   rather than failing it.
-#
-# Determinism comes from data alone: netsim is counter-driven, and retry runs
-# with `minDelay: 1`, which leaves no room for jitter (it is drawn from
-# [0, minDelay)) and costs no real time.
 
 basic: set: [
 
@@ -171,10 +136,6 @@ basic: set: [
     out: { total: { calls: 5, amount: 5 } }
   }
 
-  # The case above supplies `budget: 0`; this one omits it. They are separate
-  # cases on purpose. An implementation that reads the option into a
-  # nullable, or treats "supplied" as "set a ceiling", passes one and fails
-  # the other, and a single case cannot tell which path it took.
   {
     name: 'an omitted budget means no ceiling either'
     feature: [ { name: 'cost', active: true, unit: 1, onBudget: 'deny' } ]
@@ -183,8 +144,4 @@ basic: set: [
   }
 ]
 
-# NOT EXPRESSIBLE HERE, and deliberately left to the per-language suites.
-# `partial`, not `basic: pending`: the section RUNS, so the deferral marker
-# that means "this whole section is a hole" would be a lie here (and the
-# corpus guard promotes any deferred section that has gained cases).
 partial: 'the sink callback takes a function, which a JSON fixture cannot carry; covered per-language.'

package/project/standard/.sdk/test/primary/clean.aon

@@ -1,11 +1,4 @@
 
-# clean(ctx, val): redact sensitive values before they reach a log sink.
-#
-# The masking body is currently commented out in every port, so clean is a
-# PASSTHROUGH — and that is exactly what needs pinning across languages: a
-# port that "helpfully" implements masking early, or that clones/reshapes the
-# value on the way through, diverges from the reference without any test
-# noticing (this fixture was an empty `set: []`).
 
 basic: set: [
   { mark:10, args: [ {options:{}}, {a:'A'} ], out: {a:'A'} }

package/project/standard/.sdk/test/primary/featureAdd.aon

@@ -1,15 +1,4 @@
 
-# PENDING — this section is deliberately empty.
-#
-# featureAdd(ctx, f) mutates client._features, so a case would have to assert
-# on the shared client every other section also uses, and undo itself
-# afterwards. The runner constructs one client per spec (DEF.client) rather
-# than one per entry, so there is no isolation to build that on yet.
-#
-# An empty `set` runs ZERO cases. Runners must not treat that as a pass by
-# accident: `basic: pending` below is the MACHINE-READABLE form of this note,
-# so the guard travels into test.json with the fixture instead of living only
-# in a comment the consumer never sees.
 
 basic: pending: 'featureAdd mutates client._features; the runner builds one client per spec, not per entry, so a case cannot isolate or undo itself.'
 basic: set: []

package/project/standard/.sdk/test/primary/featureHook.aon

@@ -1,14 +1,4 @@
 
-# PENDING — this section is deliberately empty.
-#
-# featureHook(ctx, name) calls f[name] on each registered feature. Asserting
-# it needs features whose hooks are FUNCTIONS; a fixture compiles to JSON and
-# cannot carry one. Covered per-language by the feature suites.
-#
-# An empty `set` runs ZERO cases. Runners must not treat that as a pass by
-# accident: `basic: pending` below is the MACHINE-READABLE form of this note,
-# so the guard travels into test.json with the fixture instead of living only
-# in a comment the consumer never sees.
 
 basic: pending: 'featureHook calls f[name] on each registered feature; a fixture compiles to JSON and cannot carry a function.'
 basic: set: []

package/project/standard/.sdk/test/primary/featureInit.aon

@@ -1,14 +1,4 @@
 
-# PENDING — this section is deliberately empty.
-#
-# featureInit(ctx, f) calls f.init(ctx, fopts). `init` is a function, and a
-# fixture compiles to JSON, so the subject of the test cannot be expressed
-# here at all. Covered per-language by the feature suites.
-#
-# An empty `set` runs ZERO cases. Runners must not treat that as a pass by
-# accident: `basic: pending` below is the MACHINE-READABLE form of this note,
-# so the guard travels into test.json with the fixture instead of living only
-# in a comment the consumer never sees.
 
 basic: pending: 'featureInit calls f.init(ctx, fopts); init is a function, and a fixture compiles to JSON, so the subject cannot be expressed here.'
 basic: set: []

package/project/standard/.sdk/test/primary/fetcher.aon

@@ -1,14 +1,4 @@
 
-# PENDING — this section is deliberately empty.
-#
-# Needs a live or mocked transport and a client instance; the shared runner
-# has no transport-injection hook. Covered per-language by the netsim and
-# feature suites until this fixture can express a transport.
-#
-# An empty `set` runs ZERO cases. Runners must not treat that as a pass by
-# accident: `basic: pending` below is the MACHINE-READABLE form of this note,
-# so the guard travels into test.json with the fixture instead of living only
-# in a comment the consumer never sees.
 
 basic: pending: 'Needs a live or mocked transport and a client instance; the shared runner has no transport-injection hook.'
 basic: set: []

package/project/standard/.sdk/test/primary/makeFetchDef.aon

@@ -1,14 +1,4 @@
 
-# PENDING — this section is deliberately empty.
-#
-# Depends on a fully built ctx (spec + point + options) that the shared
-# runner cannot assemble from a literal map. Covered indirectly by
-# makeSpec/makeUrl, and by the per-language pipeline suites.
-#
-# An empty `set` runs ZERO cases. Runners must not treat that as a pass by
-# accident: `basic: pending` below is the MACHINE-READABLE form of this note,
-# so the guard travels into test.json with the fixture instead of living only
-# in a comment the consumer never sees.
 
 basic: pending: 'Depends on a fully built ctx (spec + point + options) that the runner cannot assemble from a literal map.'
 basic: set: []

package/project/standard/.sdk/test/primary/makePoint.aon

@@ -1,22 +1,4 @@
 
-# makePoint chooses which endpoint definition ("point") an operation call
-# should use, and records it on ctx.point.
-#
-# The whole selection is driven by DATA: `op` is rebuilt by Context from
-# `opname` + `entity.name` + `config.entity.<name>.op.<opname>.points`, and
-# `options.allow.op` gates the call. So every branch below is expressible as
-# a literal ctx, contrary to the deferral note this fixture used to carry,
-# which claimed it needed a real client.
-#
-# Errors are RETURNED, not thrown, and their JSON embeds a random ctx id, so
-# the error cases assert `match: out: code` rather than a whole-value `out`.
-# Go returns the error as a second result instead, and its runner normalises
-# it to the same `{code}` shape.
-#
-# `allow.op` is a COMMA-SEPARATED STRING, not a list — that is what the client
-# actually carries. Go reads it with strings.Contains and type-asserts to
-# string, so a list here silently denies every operation; TS's .includes()
-# accepts either and would have hidden the mismatch.
 
 basic: set: [
 
@@ -59,8 +41,6 @@ basic: set: [
     match: { out: { code: 'point_no_points' } }
   }
 
-  # Two points: `select.exist` picks the one whose required keys are present
-  # in the match. `id` is supplied, so the by-id point wins.
   {
     ctx: {
       opname: 'list'
@@ -75,8 +55,6 @@ basic: set: [
     out: { method: 'GET', path: ['byid'], select: { exist: ['id'] } }
   }
 
-  # Same two points, but `id` is absent — the exist check fails and selection
-  # falls through to the unconstrained point.
   {
     ctx: {
       opname: 'list'

package/project/standard/.sdk/test/primary/makeResult.aon

@@ -1,18 +1,4 @@
 
-# PENDING — this section is deliberately empty.
-#
-# makeResult needs a ctx carrying a constructed Spec AND Result, built via the
-# SDK's own NewSpec/NewResult constructors, plus the absent-error path for
-# each. The runner builds ctx from a literal map and has no constructor hook,
-# so these cannot be expressed here yet — covered per-language today (e.g.
-# go's makeResult-basic / -no-spec / -no-result), which is exactly the drift
-# this corpus exists to remove. Promoting it needs a runner change, not just
-# fixture data.
-#
-# An empty `set` runs ZERO cases. Runners must not treat that as a pass by
-# accident: `basic: pending` below is the MACHINE-READABLE form of this note,
-# so the guard travels into test.json with the fixture instead of living only
-# in a comment the consumer never sees.
 
 basic: pending: 'Needs a ctx carrying a Spec AND Result built via the SDK constructors; the runner builds ctx from a literal map and has no constructor hook.'
 basic: set: []

package/project/standard/.sdk/test/primary/prepareAuth.aon

@@ -1,10 +1,5 @@
 
 DEF: {
-  # auth pinned explicitly (not left to a spec's own derived prefix/scheme):
-  # this corpus tests the raw single-token mechanics in isolation, so it
-  # must not silently inherit whatever a given SDK's real spec declares
-  # (e.g. genuine HTTP Basic Auth, a non-empty prefix, two credentials) -
-  # that has its own dedicated coverage elsewhere.
   setup: a: { apikey: 'APIKEY01', auth: { prefix: '', basic: false } }
 }
 

package/project/standard/.sdk/test/primary/preparePath.aon

@@ -1,11 +1,4 @@
 
-# preparePath: join ctx.point.parts with '/', dropping empty segments.
-#
-# Path templating is the highest-risk request-shaping step, and this fixture
-# was an empty `set: []` — so every language "passed" it while running zero
-# cases. The cases below were lifted from the per-language hand-written tests
-# (go/py) that had drifted out of the shared corpus, plus the empty/blank
-# segment edges that `join(..., true)` is specifically responsible for.
 
 basic: set: [
   # Multi-segment path, placeholder left intact (params are substituted later,

package/project/standard/.sdk/test/struct/nullsem.aon

@@ -1,102 +1,21 @@
 
-# STORED-NULL SEMANTICS.
-#
-# One question, asked of every reader: when a key is PRESENT and holds a JSON
-# null, is that "no value" (the same as an absent key) or is it a value?
-#
-# Nothing in the corpus asked it before. `minor.getprop` and `minor.haskey`
-# have ~50 cases each and not one stores a null: every entry is an absent key
-# or a non-null value. So the ports diverged silently, and they HAVE:
-#
-#   port   getprop({x:null},'x','ALT')   haskey({x:null},'x')
-#   ────   ───────────────────────────   ────────────────────
-#   go     'ALT'                         false
-#   py     'ALT'                         false
-#   perl   'ALT'                         false
-#   rb      null                         true
-#   php     null                         true
-#   js      null                         true
-#
-# That is not academic. It is the direct cause of the `auth: null` bug family:
-# `auth: null` is the documented way to suppress auth outright, and where a
-# stored null reads as "no value" the optspec `auth` default fires, the
-# suppression becomes "use the default auth", and the credential the caller
-# withheld goes out on the wire.
-#
-# 0.3.2 answers "no value" — the top three rows. This section pins that.
-#
-#
-# THIS SECTION IS OPT-IN, AND DELIBERATELY SO.
-#
-# Half the tree still vendors a struct that answers the other way. Putting
-# these cases in `minor` would red those targets today and gate the whole
-# corpus on finishing the struct migration everywhere first. Instead a target
-# wires this section up as it migrates:
-#
-#   runsetflags(nullsemSpec["getprop"], {"null": False}, getprop_wrapper)
-#
-# so the section becomes that target's null-semantics gate, and a target that
-# has not migrated simply does not reference it yet.
-#
-#
-# `null: false` IS NOT OPTIONAL HERE.
-#
-# The runner's default fixJSON rewrites every JSON null - on BOTH the `in` and
-# `out` sides - to the string '__NULL__' before the subject ever sees it. Run
-# without the flag, every case below would pass the STRING '__NULL__' as the
-# stored value, which is not a null and is not the question. The section would
-# then pass on every port while asserting nothing about null at all - the
-# exact "green while checking nothing" failure the corpus guards exist to
-# prevent. `minor.getelem` and `minor.clone` already run with the flag for the
-# same reason.
-#
-# With the flag, an entry with NO `out` expects a null result, and `out:` with
-# a value expects that value.
-#
-#
-# VERIFIED AGAINST THE REFERENCE, NOT GUESSED.
-#
-# All 33 cases below were run against upstream @voxgig/struct 0.3.2
-# (typescript/src/StructUtility.ts, the canonical port) and all 33 pass. They
-# are what the reference DOES, not what it was assumed to do.
-#
-# That mattered on the first run: `getprop([null], 0, 'ALT')` was assumed to
-# be a formality and turned out to be a live defect in the py port's vendored
-# copy. Canonical getprop tests `isnode(val)` - map AND list - and then
-# applies the null rule once to whatever it read. The py copy branches on
-# ismap/islist and its list branch does `return val[key]`, an early return
-# that skips the null check entirely, so it hands back the stored null where
-# every other reader would substitute the alt. Its map path is correct, which
-# is why nothing noticed.
-#
-# So py cannot opt in to this section until its vendored struct is resynced.
-# That is the section working as intended: it says "not yet" in a test result
-# instead of in a comment.
-
-
-# Does the ALT fire for a stored null, as it does for an absent key?
+
+
 getprop: {
   set: [
-    # THE CASE. Absent and stored-null must answer alike.
     { in: { val: {x:null}, key: x, alt: 'ALT' }, out: 'ALT' }
     { in: { val: {},       key: x, alt: 'ALT' }, out: 'ALT' }
 
-    # No alt: a stored null reads back as null either way, so this pins that
-    # the rule does not turn a null into something else.
     { in: { val: {x:null}, key: x } }
 
     # A stored null must not leak past its own key.
     { in: { val: {x:null, y:1}, key: y, alt: 'ALT' }, out: 1 }
     { in: { val: {x:1, y:null}, key: x, alt: 'ALT' }, out: 1 }
 
-    # false, 0 and '' are VALUES, not absence. A port that collapses "nullish"
-    # to "falsy" passes every case above and fails these.
     { in: { val: {x:false}, key: x, alt: 'ALT' }, out: false }
     { in: { val: {x:0},     key: x, alt: 'ALT' }, out: 0 }
     { in: { val: {x:''},    key: x, alt: 'ALT' }, out: '' }
 
-    # Lists too: index 0 holding a null is the list-shaped form of the same
-    # question, and a port can easily fix one and not the other.
     { in: { val: [null], key: 0, alt: 'ALT' }, out: 'ALT' }
     { in: { val: [null, 1], key: 1, alt: 'ALT' }, out: 1 }
   ]
@@ -111,8 +30,6 @@ getelem: {
     { in: { val: [10, null, 30], key: 1, alt: 'ALT' }, out: 'ALT' }
     { in: { val: [10, null, 30], key: 2, alt: 'ALT' }, out: 30 }
 
-    # Negative indices are getelem's whole reason for existing; a stored null
-    # at a negative index is the case a port is most likely to miss.
     { in: { val: [10, null], key: -1, alt: 'ALT' }, out: 'ALT' }
     { in: { val: [null, 20], key: -1, alt: 'ALT' }, out: 20 }
 
@@ -137,15 +54,12 @@ getpath: {
 }
 
 
-# Presence, asked directly. This is the reader the auth-null fix needs in
-# every port, and the one whose answer splits the tree.
 haskey: {
   set: [
     { in: { src: {x:null}, key: x }, out: false }
     { in: { src: {},       key: x }, out: false }
     { in: { src: {x:1},    key: x }, out: true }
 
-    # Again: falsy is not absent.
     { in: { src: {x:false}, key: x }, out: true }
     { in: { src: {x:0},     key: x }, out: true }
     { in: { src: {x:''},    key: x }, out: true }
@@ -156,13 +70,6 @@ haskey: {
 }
 
 
-# The other direction, and the reason `auth: null` is expressible at all:
-# presence is STRUCTURAL. keysof lists a null-valued key, because the key IS
-# there - it is only the READERS above that treat its value as no value.
-#
-# A port that made haskey false by DELETING the key would pass every case
-# above and fail here, and it would also make the suppression unwritable:
-# there would be nothing left for makeOptions to detect.
 keysof: {
   set: [
     { in: {a:null}, out: [a] }