@voxgig/sdkgen 4.21.0 → 4.22.0

package/project/.sdk/tm/ts/src/feature/validate/ValidateFeature.ts

@@ -6,30 +6,6 @@ import { ENTITYSPEC } from '../../Schema'
 import { BaseFeature } from '../base/BaseFeature'
 
 
-// Payload validation against the model's own field types.
-//
-// The specs are NOT written here and not written in the model either: every
-// entity field already carries a canonical type sentinel (`$STRING`,
-// `$INTEGER`, the `$ONE` union for an OpenAPI multi-type), which is the same
-// vocabulary struct.validate speaks. The generator maps them once
-// (helpers/canonSpec) and emits `ENTITYSPEC` beside this file, so a field
-// whose type changes in the API spec changes what this feature enforces with
-// no edit anywhere.
-//
-// WHAT IS CHECKED
-//   outbound (PreSpec)  the payload the caller asked to send, against
-//                       `spec.op[<opname>]` — the operation's request shape,
-//                       which is the SAME partiality policy that decides what
-//                       the generated `<Name>CreateData` type requires.
-//   inbound  (PreDone)  each record the operation returned, against
-//                       `spec.data` — the entity's own field types.
-//
-// WHAT IS NOT. The model carries no array element types, no nested object
-// schemas, no enums, formats or bounds (see canonSpec's note), so this checks
-// the shape the model knows and nothing more. It is a guard against the
-// mistakes the model CAN see — a number where a string belongs, a required
-// field left out, a misspelled key under `strict` — not a substitute for the
-// server's own validation.
 class ValidateFeature extends BaseFeature {
   version = '0.0.1'
   name = 'validate'
@@ -49,12 +25,6 @@ class ValidateFeature extends BaseFeature {
     this._options = options || {}
     this.active = (options as any).active
 
-    // DEFAULTS ARE APPLIED HERE, not by the option spec. The model's
-    // `config.options` documents them and types them; it does not inject
-    // them, because each feature entry in the spec is optional and struct
-    // fills in nothing through an optional union. So every feature resolves
-    // its own — and a `mode` left undefined here once meant `'throw' !==
-    // undefined`, which silently turned every rejection into a no-op.
     this._request = false !== this._options.request
     this._response = true === this._options.response
 
@@ -64,16 +34,10 @@ class ValidateFeature extends BaseFeature {
     // rejects the typo outright; this is what happens if it ever does not.
     this._mode = 'report' === this._options.mode ? 'report' : 'throw'
 
-    // `strict` is applied ONCE, here, by rebuilding the spec tree without the
-    // `$OPEN` markers — rather than per call, which would clone a spec for
-    // every request an SDK ever makes.
     this._spec = true === this._options.strict ? close(ENTITYSPEC) : ENTITYSPEC
   }
 
 
-  // Outbound. `makeSpec` short-circuits on an `ctx.out.spec` that is already
-  // set, so assigning the error here rejects the operation before the request
-  // is built — the same seam rbac uses one stage earlier.
   PreSpec(this: any, ctx: any) {
     if (!this.active || !this._request) {
       return
@@ -100,22 +64,6 @@ class ValidateFeature extends BaseFeature {
   }
 
 
-  // Inbound. PreDone rather than PreResult: the records are extracted from
-  // the response body by `makeResult`, which runs between the two, so at
-  // PreResult there is nothing to check but the envelope.
-  //
-  // HOOK ORDER MATTERS HERE, and the default order is not the one you want.
-  // PreDone hooks fire in feature ADD order, which defaults to `test` first
-  // and then names sorted — and `validate` sorts last, after `audit`,
-  // `cost`, `debug`, `metrics` and `telemetry`. Those observers therefore
-  // record the operation as a success before this hook has looked at it.
-  // Activating features as an ORDERED ARRAY fixes it:
-  //
-  //   feature: [{ name: 'validate', active: true, response: true },
-  //             { name: 'metrics', active: true }]
-  //
-  // What this feature can fix from here, it does: the result is marked
-  // failed and its records are cleared, so the entity absorbs nothing.
   PreDone(this: any, ctx: any) {
     if (!this.active || !this._response) {
       return
@@ -140,10 +88,6 @@ class ValidateFeature extends BaseFeature {
         continue
       }
 
-      // A NON-OBJECT IS A FAILURE, not something to skip. A load that
-      // answered `42` where the entity's spec wants a record used to pass
-      // this feature silently, which is the one outcome a validator must
-      // never produce. struct rejects it with the field it could not find.
       for (const e of this._check(ctx, unwrap(record), spec.data, 'response')) {
         errs.push(e)
       }
@@ -156,33 +100,15 @@ class ValidateFeature extends BaseFeature {
     const err = ctx.error('validate_failed',
       'Invalid response for entity "' + entname(ctx) + '": ' + errs.join('; '))
 
-    // BOTH, and `ok` is the load-bearing half: `done` returns `resdata`
-    // whenever `result.ok` is true and never looks at `err`, so setting the
-    // error alone handed the caller the very records that failed the spec.
     ctx.result.ok = false
     ctx.result.err = err
 
-    // AND THE DATA GOES. The load/update fragments copy `result.resdata`
-    // into the entity's own state on any non-null value, BEFORE `done`
-    // raises — so rejecting the operation while leaving the records in place
-    // left the caller holding an entity populated from a payload this
-    // feature had just declared invalid. Clearing it is the only half of
-    // that this feature owns; see the note on hook order below.
     ctx.result.resdata = undefined
 
     return err
   }
 
 
-  // The payload an operation is about to send.
-  //
-  // TWO SLOTS, AND THE OP PICKS. A body op (create/update/patch) carries the
-  // caller's argument in `reqdata` over the entity's `data`; a match op
-  // (load/list/remove) carries it in `reqmatch` over `match`. That is what
-  // the Entity*Op fragments pass to makeContext and what makePoint reads
-  // (`getprop(ctx, 'req' + op.input)`) — so reading `reqdata` for every op
-  // checked a `load({ id })` against the entity's STALE stored match and
-  // rejected it for the id the caller had just supplied.
   _payload(this: any, ctx: any, opname: string): Record<string, any> {
     const body = 'create' === opname || 'update' === opname || 'patch' === opname
 
@@ -207,9 +133,6 @@ class ValidateFeature extends BaseFeature {
   }
 
 
-  // One validate call. Errors are COLLECTED, never thrown: struct throws on
-  // the first failure unless given an `errs` array, and a caller fixing a
-  // payload wants every problem with it, not the first one.
   _check(this: any, ctx: any, data: any, spec: any, direction: string): string[] {
     const struct = ctx.utility.struct
     const errs: string[] = []
@@ -242,13 +165,6 @@ class ValidateFeature extends BaseFeature {
 }
 
 
-// A RESULT RECORD AS DATA.
-//
-// `makeResult` turns every record of a LIST into an entity instance
-// (`entity.make()` then `ent.data(entry)`), so what reaches PreDone for a
-// list is wrappers, not records — and a wrapper checked against a field spec
-// fails on every required field while its actual data goes unchecked. A load
-// returns the record itself, so this has to handle both.
 function unwrap(record: any): any {
   if (null != record && 'function' === typeof record.data) {
     const data = record.data()
@@ -265,9 +181,6 @@ function entname(ctx: any): string {
 }
 
 
-// The spec tree with every `$OPEN` marker removed, so an undeclared key is an
-// error rather than a pass. Rebuilt rather than mutated: ENTITYSPEC is a
-// module constant shared by every client in the process.
 function close(node: any): any {
   if (Array.isArray(node)) {
     return node.map((n: any) => close(n))

package/project/.sdk/tm/ts/src/utility/CleanUtility.ts

@@ -14,18 +14,6 @@ function clean(ctx: Context, val: any) {
   const cleankeyre = options?.__derived__?.clean?.keyre
   const hintsize = 4
 
-  /*
-  if (null != cleankeyre) {
-    val = walk(clone(val), (key: any, subval: any) => {
-      if (cleankeyre.exec(key) && 'string' === typeof subval) {
-        const len = size(subval)
-        const hint = (hintsize * 4) < len ? slice(subval, 0, hintsize) : ''
-        subval = pad(hint, len, '*')
-      }
-      return subval
-    })
-  }
-  */
 
   return val
 }

package/project/.sdk/tm/ts/src/utility/FeatureAddUtility.ts

@@ -12,7 +12,6 @@ function featureAdd(ctx: Context, f: Feature) {
   let added = false
   const features = client._features
 
-  // TODO: make this a utility
   if (fopts.__before__ || fopts.__after__ || fopts.__replace__) {
 
     for (let i = 0; i < features.length; i++) {

package/project/.sdk/tm/ts/src/utility/GraphqlUtility.ts

@@ -2,23 +2,8 @@
 import { Context } from '../types'
 
 
-// GraphQL transport. API-INDEPENDENT: every GraphQL SDK this generator
-// produces uses this file unchanged. The API-specific part — which
-// operations exist and what each one's document is — is model data,
-// computed once by apidef and emitted into Config.
-//
-// Two jobs:
-//
-//   graphqlBody    — build { query, variables } for a point, binding the
-//                    op's arguments to the document's declared variables.
-//
-//   graphqlErrors  — lift a GraphQL failure into an SDK error. GraphQL
-//                    reports failures as a top-level `errors` array under
-//                    HTTP 200, so the status-driven path in resultBasic
-//                    never sees them.
-
-
-// Content type every GraphQL-over-HTTP request uses.
+
+
 const GRAPHQL_CONTENT_TYPE = 'application/json'
 
 
@@ -47,12 +32,6 @@ function graphqlErrorCode(gqlerr: any): string {
 }
 
 
-// Build the request body for a GraphQL point.
-//
-// Variables come from the op's own arguments: a named variable binds to the
-// like-named argument (`from`), and the input-object variable (empty `from`)
-// takes the request data as a whole — which is what makes a generated
-// create/update call look exactly like its REST equivalent.
 function graphqlBody(ctx: Context): any {
   const utility = ctx.utility
   const struct = utility.struct
@@ -105,13 +84,6 @@ function graphqlBody(ctx: Context): any {
 }
 
 
-// Inspect a decoded GraphQL response body and record a failure when the
-// server reported one. Returns true when an error was recorded.
-//
-// Partial data (`data` alongside `errors`) is treated as failure: the REST
-// surface has no partial-success concept, and silently returning half an
-// object would be worse than failing. The raw envelope stays available on
-// the result for callers that need it.
 function graphqlErrors(ctx: Context): boolean {
   const result: any = ctx.result
   const point: any = ctx.point

package/project/.sdk/tm/ts/src/utility/MakeErrorUtility.ts

@@ -23,9 +23,6 @@ function makeError(ctx: Context, err?: any) {
   err = err || ctx.error('unknown', 'unknown error')
 
   const errmsg = err.message || 'unknown error'
-  // TODO: project name should come from config
-  // avoids spurious changes between template and generated utility
-  // applies for all utility files
   const msg = 'ProjectNameSDK: ' + op.name + ': ' + errmsg
   err.message = clean(ctx, msg)
 
@@ -61,7 +58,6 @@ function makeError(ctx: Context, err?: any) {
     ctx.utility.featureHook(ctx, 'PreUnexpected')
   }
 
-  // TODO: model option to return instead
   if (false === ctx.ctrl.throw) {
     return result.resdata
   }

package/project/.sdk/tm/ts/src/utility/MakeOptionsUtility.ts

@@ -15,25 +15,8 @@ function makeOptions(ctx: Context) {
 
   let opts = { ...(options || {}) }
 
-  // EXPLICIT AUTH SUPPRESSION, captured BEFORE merge and validate.
-  //
-  // `auth: null` is the documented way to disable auth outright, and
-  // prepareAuth honours it. But struct 0.3.2's getprop treats a stored
-  // null as "no value", so validate fills in the optspec's `auth`
-  // default and the suppression silently became "use default auth" —
-  // transmitting a credential the caller explicitly asked not to send.
-  // (0.0.10 rejected `auth: null` outright, so nothing depended on the
-  // old behaviour, and nothing catches the new one.)
-  //
-  // Suppliedness cannot be recovered after validate, hence here.
   const authSuppressed = null === (options || {}).auth
 
-  // Feature add-order. `options.feature` may be given as an ordered ARRAY of
-  // { name, active, ...opts } entries (the array position IS the order in
-  // which features are added), or as a { name: {opts} } map. Normalize an
-  // array to a map (so merge/validate/init are unchanged) and remember the
-  // explicit order; a map defaults to test-first so the `test` mock transport
-  // is installed as the base of the transport wrapper chain.
   let featureorder: string[] = []
   if (Array.isArray(opts.feature)) {
     const fmap: any = {}
@@ -55,18 +38,6 @@ function makeOptions(ctx: Context) {
   let config = ctx.config || {}
   let cfgopts = config.options || {}
 
-  // THE OPTION SPEC IS GENERATED, NOT WRITTEN HERE.
-  //
-  // `Spec.OPTSPEC` is built from the model: `main.kit.optspec` for the
-  // standard options, plus one entry per feature this target carries, taken
-  // from that feature's own `config.options` / `config.optspec`. Editing this
-  // file to add an option would put it back where it was — one of twenty
-  // hand-maintained copies of a schema nothing cross-checked — so add it to
-  // the model instead and every ported target validates it.
-  //
-  // NOT MUTATED. It is a module-level constant shared by every client this
-  // process constructs; the platform default below is applied to the RESULT,
-  // never to the spec.
   const optspec = OPTSPEC
 
   // Clone the config side before merging: `config` is a module-level
@@ -77,11 +48,6 @@ function makeOptions(ctx: Context) {
 
   opts = validate(opts, optspec)
 
-  // The platform fetch, supplied AFTER validate rather than as a spec
-  // default. `system.fetch` is declared `$ANY`, which passes a caller's own
-  // fetch through untouched but inserts nothing when the key is absent — and
-  // the spec is shared, so writing the default into it (as this did while the
-  // spec was a per-call literal) would hand one client's fetch to the next.
   opts.system = opts.system || {}
   if (null == opts.system.fetch) {
     opts.system.fetch = global.fetch
@@ -92,12 +58,6 @@ function makeOptions(ctx: Context) {
     opts.auth = null
   }
 
-  // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
-  // Every placeholder must resolve to a non-empty value: from
-  // options.server (user), else the Config default. A placeholder that
-  // resolves to '' is a construction ERROR in live mode — the URL cannot
-  // work — but in test mode substitutes the deterministic value
-  // `test-<name>` so offline tests need no configuration.
   if ('string' === typeof opts.base && opts.base.includes('{')) {
     const testmode = true === opts.test.active ||
       true === (opts.feature && opts.feature.test && opts.feature.test.active)
@@ -127,12 +87,6 @@ function makeOptions(ctx: Context) {
     names = names.indexOf('test') < 0
       ? names
       : ['test'].concat(names.filter((n: string) => 'test' !== n))
-    // Station special case, mirroring test's: its transport wrap must
-    // sit immediately outside the base transport (inside retry/cache/
-    // netsim), so map-form activation hoists it to just after test -
-    // or first, when no test entry exists. Without this the sorted
-    // default would init station last and wrap OUTSIDE the recording
-    // features, turning its wire-truth events into fiction.
     const si = names.indexOf('station')
     if (0 <= si) {
       names.splice(si, 1)

package/project/.sdk/tm/ts/src/utility/MakePointUtility.ts

@@ -2,28 +2,6 @@
 import { Context, Point } from '../types'
 
 
-// The entity's OWN route among an op's points, as opposed to a
-// CROSS-REFERENCE: another resource's route that happens to return this
-// entity (`/notifications/{id}/board` for a board). Both are plain GETs
-// with no `$action`, so the path itself is all there is to go on.
-//
-// Two signals, in order:
-//
-//   1. A record route ends in the record's identifier (`/boards/{id}`,
-//      `/accounts/{account_id}/users/{id}`); a cross-reference ends in the
-//      relationship's name (`/posts/{id}/author`). A terminal parameter is
-//      therefore the stronger signal, and unlike depth it survives an entity
-//      nested more deeply than the route pointing at it.
-//   2. Failing that, fewest path segments — the shallower route is the one
-//      the entity is named for.
-//
-// Ties keep the earlier point, so the sorted-key order of the model decides
-// and the output stays byte-stable.
-//
-// The same rule runs at GENERATION time, in `shortestPoint`/`ownPoint` in
-// helpers/opShape.ts. It cannot be shared with this file — a template ships
-// standalone, outside that package — so it is written twice on purpose, and
-// both sides must move together.
 function terminalParam(point: any): boolean {
   const parts = point.parts
   const last = 0 < parts.length ? parts[parts.length - 1] : ''
@@ -109,19 +87,7 @@ function makePoint(ctx: Context): Point | Error {
       }
     }
 
-    // select.exist can list more than the params needed to pick a point (for
-    // /boards/{id} it is Trello's 17 optional query-includes), so a plain
-    // {id} call matches NOTHING. Fall back to the entity's OWN route rather
-    // than whichever point came last.
     if (!matched) {
-      // A request naming an action reaches here only because that action's
-      // own point failed its exist test, so the request is unbuildable
-      // whatever we pick. Refuse it BEFORE choosing a fallback: the guard
-      // below compares the chosen point's $action, and would wave the
-      // request through whenever the action point is itself the one the
-      // fallback selects (a short action route folded into an entity whose
-      // canonical route is longer). An unbuildable action request is an
-      // error, never a silent request to some other endpoint.
       if (null != reqselector.$action) {
         return ctx.error('point_action_invalid', 'Operation "' + op.name +
           '" action "' + reqselector.$action + '" is not valid.')

package/project/.sdk/tm/ts/src/utility/MakeRequestUtility.ts

@@ -36,7 +36,6 @@ async function makeRequest(ctx: Context): Promise<Response | Error> {
 
     spec.step = 'prerequest'
 
-    // TODO: see js code, use `native` prop here
     const fetched = await fetcher(ctx, fetchdef.url, fetchdef)
 
     if (null == fetched) {

package/project/.sdk/tm/ts/src/utility/MakeSpecUtility.ts

@@ -30,7 +30,6 @@ function makeSpec(ctx: Context): Spec | Error {
 
   ctx.spec.method = prepareMethod(ctx)
 
-  // TODO: Add string utils to StructUtility
   if (!options.allow.method.includes(ctx.spec.method)) {
     return ctx.error('spec_method_allow', 'Method "' + ctx.spec.method +
       '" not allowed by SDK option allow.method value: "' + options.allow.method + '"')
@@ -41,10 +40,6 @@ function makeSpec(ctx: Context): Spec | Error {
   ctx.spec.headers = prepareHeaders(ctx)
 
   if ('graphql' === (point as any).kind) {
-    // GraphQL addresses one endpoint: no path parts, no query string, and
-    // the body carries the operation. prepareBody is skipped deliberately —
-    // it only emits a body for data-input ops (create/update), whereas every
-    // GraphQL op posts one, including load/list/remove.
     ctx.spec.body = utility.graphqlBody(ctx)
     ctx.spec.path = ''
     // prepareQuery already copied the op's match arguments into the query

package/project/.sdk/tm/ts/src/utility/MakeUrlUtility.ts

@@ -23,7 +23,6 @@ function makeUrl(ctx: Context): Error | string {
   }
 
 
-  // TODO: use parts to avoid regexp?
   let url = join([spec.base, spec.prefix, spec.path, spec.suffix], '/', true)
   let resmatch: Record<string, any> = {}
 

package/project/.sdk/tm/ts/src/utility/ParamUtility.ts

@@ -1,13 +1,6 @@
 
 import { Context } from '../types'
 
-/* Find value of a match parameter, possibly using an alias.
- *
- * The match parameter may have an alias key. For example, the parameter `foo_id` may be
- * aliased to `id` in the entity data.
- *
- * This function returns `undefined` rather than failing.
- */
 function param(ctx: Context, paramdef: any) {
   const point = ctx.point
   const spec = ctx.spec
@@ -27,7 +20,6 @@ function param(ctx: Context, paramdef: any) {
 
   const pt = typify(paramdef)
 
-  // TODO: review this search algorithm
 
   const key = 0 < (T_string & pt) ? paramdef : getprop(paramdef, 'name')
 

package/project/.sdk/tm/ts/src/utility/PrepareBodyUtility.ts

@@ -14,9 +14,6 @@ function prepareBody(ctx: Context) {
     try {
       body = transformRequest(ctx)
 
-      // if (point.check.nobody && null == body) {
-      //   return error(ctx, new Error('Request body is empty.'))
-      // }
     }
     catch (err) {
       return error(ctx, err)

package/project/.sdk/tm/ts/src/utility/PrepareParamsUtility.ts

@@ -6,16 +6,12 @@ function prepareParams(ctx: Context) {
   const utility = ctx.utility
   const findparam = utility.param
 
-  // const struct = utility.struct
-  // const validate = struct.validate
 
   const point = ctx.point
 
   let params = point.args.params
-  // let reqmatch = ctx.reqmatch
 
   params = params || []
-  // reqmatch = reqmatch || {}
 
   let out: any = {}
   for (let pd of params) {
@@ -25,8 +21,6 @@ function prepareParams(ctx: Context) {
     }
   }
 
-  // TODO: review
-  // out = validate(out, point.validate.params)
 
   return out
 }

package/project/.sdk/tm/ts/src/utility/ResultBasicUtility.ts

@@ -14,7 +14,6 @@ function resultBasic(ctx: Context) {
     result.status = getprop(response, 'status', -1)
     result.statusText = getprop(response, 'statusText', 'no-status')
 
-    // TODO: use spec!
     if (400 <= result.status) {
       const msg = 'request: ' + result.status + ': ' + result.statusText
       if (result.err) {

package/project/.sdk/tm/ts/src/utility/TransformRequestUtility.ts

@@ -1,10 +1,6 @@
 
 import { Context } from '../types'
 
-/* Convert entity data or match query into a srtucture suitable for use as request data.
- *
- * The operation (op) property `reqform` is used to perform the data preparation.
- */
 function transformRequest(ctx: Context) {
   const spec = ctx.spec
   const utility = ctx.utility
@@ -31,22 +27,6 @@ function transformRequest(ctx: Context) {
 
 
 
-// `$action` selects WHICH POINT of the op to use (see MakePointUtility). It
-// is the SDK's own discriminator, never an API field, so it must not survive
-// into the wire body. The GraphQL path already strips it where it builds its
-// input object; this is the same rule on the REST path, which had no such
-// step and sent it verbatim -- `{"$action":"merge", ...}` to GitHub's merge
-// endpoint. Harmless there, because GitHub ignores unknown keys; not
-// harmless against an API that validates its request bodies strictly.
-//
-// Only a top-level key of a plain object: a body may legitimately be an
-// array or a scalar, and neither can carry a selector.
-//
-// `__proto__` is assigned through Object.defineProperty, never `body[key] =`.
-// It is a legal JSON key and can be a real API field, but plain assignment
-// invokes the inherited setter: the key would vanish from the serialised
-// request and silently become the body's prototype instead. Same treatment
-// as StructUtility's condenseSet, for the same reason.
 
 function stripAction(reqdata: any) {
   if (null == reqdata || 'object' !== typeof reqdata || Array.isArray(reqdata)) {

package/project/.sdk/tm/ts/src/utility/TransformResponseUtility.ts

@@ -2,10 +2,6 @@
 import { Context } from '../types'
 
 
-/* Convert data from respnse into a structure suitable for use as entity data.
- *
- * The operation (op) property `resform` is used to perform the data extraction.
- */
 function transformResponse(ctx: Context) {
   const spec = ctx.spec
   const result = ctx.result

package/project/.sdk/tm/ts/test/exists.test.ts

@@ -8,16 +8,6 @@ import { ProjectNameSDK } from '..'
 
 describe('exists', async () => {
 
-  // NOT async, and the assertion is deliberate.
-  //
-  // ProjectNameSDK.test() is synchronous — it returns the client, not a promise
-  // — so the `await` here was a no-op. Worse, it hid the weakness of the
-  // assertion: `null !== testsdk` is trivially true for ANY non-null value,
-  // including the promise an `await` would have unwrapped. The test could not
-  // have failed short of test() returning null.
-  //
-  // instanceof is the real check: it fails if test() ever starts returning a
-  // promise, or anything other than a client.
   test('test-mode', () => {
     const testsdk = ProjectNameSDK.test()
     equal(testsdk instanceof ProjectNameSDK, true,

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

@@ -1,20 +1,4 @@
 
-// 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.
 
 import { test, describe, before } from 'node:test'
 import { ok, deepStrictEqual } from 'node:assert'
@@ -25,12 +9,6 @@ import { join } from 'node:path'
 import { SDK, TEST_JSON_FILE } from '../utility/index'
 
 
-// Features with a corpus section — read from the corpus itself, so a
-// project-authored section (a custom feature added under
-// .sdk/test/feature/) runs without editing this file. Read eagerly: the
-// node test runner collects the per-feature tests at describe time,
-// before any `before` hook fires. An SDK generated without a listed
-// feature still skips, not fails.
 const FEATURES = Object.keys((() => {
   try {
     return JSON.parse(readFileSync(
@@ -86,14 +64,6 @@ function scriptedFetcher(res: any[]) {
 
 
 function makeClient(kase: any): any {
-  // `test: { active: true }` is the OPTION, not the `test` FEATURE.
-  //
-  // It says "this client is not live", which is what makes a REQUIRED
-  // OpenAPI server variable resolve to a deterministic `test-<name>`
-  // rather than refuse to construct (see makeOptions). It installs no
-  // transport, so the scripted fetcher below still stands — the FEATURE
-  // is transport: 'base' and would shadow it, which is why this cannot
-  // just turn the feature on.
   return new (SDK as any)({
     test: { active: true },
     feature: kase.feature,
@@ -102,13 +72,6 @@ function makeClient(kase: any): any {
 }
 
 
-// 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: any): OpRef[] {
   const entities: Record<string, any> = client._rootctx.config.entity || {}
 
@@ -131,14 +94,6 @@ function candidates(client: any): OpRef[] {
     }
   }
 
-  // SAFE OPS FIRST. The corpus calls #OP1 repeatedly and reasons about what
-  // the transport did in between — a cache hit, a retry, a rate-limit wait.
-  // `load`/`list` are the GET ops, and the cache stores only successful GETs,
-  // so an SDK whose first usable op is a `create` (POST) can never satisfy
-  // "a hit served from cache costs nothing": nothing is ever cached, the
-  // second call goes to the network, and cost correctly charges twice. That
-  // reads as a cost defect and is not one. Ordering here rather than
-  // filtering keeps every SDK runnable, including ones with no GET at all.
   const SAFE: Record<string, number> = { list: 0, load: 1 }
   return out.sort((a, b) =>
     (SAFE[a.op] ?? 2) - (SAFE[b.op] ?? 2) || a.key.localeCompare(b.key))
@@ -223,17 +178,6 @@ describe('FeatureCorpus', () => {
   })
 
 
-  // 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(