@voxgig/sdkgen 4.21.0 → 4.23.0

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(

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

@@ -1,13 +1,4 @@
 
-// Offline feature-test harness for the generated SDK.
-//
-// Feature behaviour (retry, cache, rbac, telemetry, ...) is unit-tested by
-// driving each feature class through a faithful miniature of the real
-// operation pipeline against a configurable mock transport — the same hook
-// order and short-circuit rules as the generated Entity*Op code, but with
-// no live server and no API-specific fixtures. Feature instances are built
-// via `config.makeFeature`, so only features actually present in this SDK
-// are exercised (see `hasFeature`).
 
 import { config, stdutil } from '../..'