@voxgig/sdkgen 4.21.0 → 4.23.0

package/src/helpers/opShape.ts

@@ -1,30 +1,3 @@
-// Per-op request-payload shape + partiality policy for the typed-model
-// generators (EntityTypes_<lang>.ts).
-//
-// SINGLE SOURCE OF TRUTH for two things every language generator needs:
-//   1. The type-name scheme: <Name>{Load,List,Remove}Match /
-//      <Name>{Create,Update}Data (OP_SUFFIX + opTypeName).
-//   2. Which fields make up an op's request payload, and whether each is
-//      required or optional (opRequestShape) — i.e. the partiality policy.
-//
-// PARTIALITY POLICY
-//   Op-declared params win: if the op declares params
-//   (op.<name>.points[].args.params[]), the payload is built from them and a
-//   param is optional iff `reqd === false` (this is how path/query params such
-//   as {id} become required). `fromParams` is true in that case.
-//
-//   Otherwise the payload mirrors the entity's fields, filtered to those active
-//   for the op (field.op[opname].active !== false; absent -> participates), and
-//   optionality is decided per-op:
-//     create -> required iff `field.req` (server-shaped required fields);
-//     update -> all optional (patch);
-//     load / remove -> a field named `id` is required, the rest optional
-//       (best-effort key convention; degrades to all-optional if no `id`);
-//     list -> all optional (filter).
-//
-// The generators consume `items` (each already carrying its final `optional`
-// flag) and render them in the target language's struct/interface/TypedDict
-// syntax; the policy itself is language-neutral and tested in isolation.
 
 import { each, names } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
@@ -32,23 +5,6 @@ import { KIT, getModelPath } from '@voxgig/apidef'
 import { pointSegments, pointTerminalParam, pointPathKey } from './pointPath'
 
 
-// THE entity collection for a model — resolved once, with a stable identity.
-//
-// Two problems this solves, both caused by every component calling
-// `getModelPath(model, 'main.<KIT>.entity')` for itself:
-//
-//   * CORRECTNESS. getModelPath drops `active: false` entries by default, but
-//     the consumer scaffold (create-sdkgen Root.ts) generates entity code for
-//     EVERY entity and every EntityTypes_<lang> emits data types with
-//     `only_active: false`. Class-name assignment done against the filtered
-//     view cannot see the inactive entities whose data types it must avoid.
-//     This resolver always returns the unfiltered collection.
-//
-//   * PERFORMANCE. getModelPath REBUILDS the container object on every call
-//     when filtering, so the WeakMap memos below never hit across callers —
-//     the O(n·ops) class-name assignment re-ran per entity per target. At 500
-//     entities x 22 targets that was ~15s of pure recomputation; caching the
-//     resolved collection on the model makes it ~3ms.
 const _entityCollCache = new WeakMap<object, any>()
 
 function entityCollection(model: any): any {
@@ -67,16 +23,6 @@ function entityCollection(model: any): any {
 }
 
 
-// Derive the PascalCase `Name` on every entity in a collection.
-//
-// `Name` is injected LAZILY by jostraca's names(), historically by whichever
-// component happened to run first (create-sdkgen Root.ts, or an EntityTypes
-// emitter). Anything reading `e.Name` before that ran saw `undefined` — and
-// because the helpers below MEMOISE, one early read poisoned the result for
-// the whole run (`undefinedEntity` class names; a permanently empty collision
-// list). The helpers therefore derive `Name` themselves, up front, so they
-// never depend on component ordering. Idempotent: names() is only called for
-// an entity that lacks `Name`.
 function deriveEntityNames(entityColl: any): any[] {
   const ents = each(entityColl).filter((e: any) => e && null != e.name)
   ents.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
@@ -100,14 +46,11 @@ function cap(s: string): string {
 }
 
 
-// The generated type name for an op's request payload, e.g. AdviceLoadMatch.
 function opTypeName(Name: string, opname: string): string {
   return Name + cap(opname) + (OP_SUFFIX[opname] || 'Match')
 }
 
 
-// One request-payload member: a model field or op param, with the final
-// required/optional decision already applied per the partiality policy.
 type OpShapeItem = {
   name: string
   type: any     // canonical type sentinel (e.g. `$STRING`); render via canonToType
@@ -115,42 +58,19 @@ type OpShapeItem = {
 }
 
 
-// Collect an op's params, deduped by name across its points.
-//
-// Points tagged with `select.$action` are sub-resource/action routes folded
-// into the op (e.g. POST .../components/{component_id}/page_access_groups on
-// the create op); they do not describe the op's canonical request payload,
-// so they are excluded — unless the op consists only of action points.
-//
-// Requiredness merges by INTERSECTION: with several alternative canonical
-// points, a param the caller must always supply is one required by every
-// point; a param only some routes use is optional in the merged shape.
-// (Union-required makes the common route untypeable — e.g. a plain
-// list-by-parent-id call failing because sibling routes' ids are demanded —
-// and steers callers into passing keys that flip runtime point dispatch to
-// the wrong route.)
-// The action names an op multiplexes, from its points' `select.$action`.
-//
-// A custom POST route like `/api/planet/{id}/terraform` is folded into the
-// `create` op as an alternative point, discriminated at call time by
-// `$action` in the data argument. The mechanism worked and was documented
-// NOWHERE — not in the README, not in the reference — so for an API with two
-// such routes, two of its six endpoints were unreachable by anyone using the
-// documented interface. Generated docs list them via this helper.
 function opActions(op: any): { action: string, path: string }[] {
   const points: any[] = op && op.points ? each(op.points) : []
 
   return points
-    .filter((pt: any) => null != (pt && pt.select && pt.select['$action']))
+    .filter((pt: any) => null != (pt && pt.q && pt.q['$action']))
     .map((pt: any) => ({
-      action: String(pt.select['$action']),
-      path: String(pt.orig || ''),
+      action: String(pt.q['$action']),
+      path: String(pt.o || ''),
     }))
     .sort((a, b) => a.action < b.action ? -1 : a.action > b.action ? 1 : 0)
 }
 
 
-// True when any of the entity's ops multiplexes a custom action.
 function entityActions(entity: any): { op: string, action: string, path: string }[] {
   const out: { op: string, action: string, path: string }[] = []
 
@@ -162,12 +82,6 @@ function entityActions(entity: any): { op: string, action: string, path: string
 }
 
 
-// The entity's own API path — the route a reader should recognise it by.
-//
-// NOT `points[0]` across every op flattened. Ops iterate in sorted-key order,
-// so `create` came first, and an entity whose create op folds in a custom
-// action (`/api/planet/{id}/forbid`) advertised THAT as its path. The
-// canonical route is the collection or record route, and never an action.
 function entityPath(entity: any): string {
   const ops: any = (entity && entity.op) || {}
 
@@ -179,11 +93,11 @@ function entityPath(entity: any): string {
 
     const points: any[] = op.points ? each(op.points) : []
     const canonical = points.filter((pt: any) =>
-      null == (pt && pt.select && pt.select['$action']))
+      null == (pt && pt.q && pt.q['$action']))
 
     const pick = (0 < canonical.length ? canonical : points)[0]
-    if (null != pick && null != pick.orig && '' !== pick.orig) {
-      return String(pick.orig)
+    if (null != pick && null != pick.o && '' !== pick.o) {
+      return String(pick.o)
     }
   }
 
@@ -191,39 +105,11 @@ function entityPath(entity: any): string {
 }
 
 
-// The entity's OWN endpoint among an op's points.
-//
-// The other notion of canonical above — "not a `$action` route" — separates a
-// folded-in custom action from the real op. This one separates the entity's
-// own route from 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
-//      the stronger signal, and unlike depth alone it survives an entity
-//      nested more deeply than the route that points at it — depth by itself
-//      picked `/posts/{id}/author` over `/accounts/{account_id}/users/{id}`
-//      and then generated that op's required params from the wrong route.
-//   2. Failing that, fewest path segments — the shallower route is the one
-//      the entity is named for, which is what settles a `list` op where
-//      neither route ends in an id (`/boards` over `/members/{id}/boards`).
-//
-// 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 RUNTIME, in each language's makePoint template, when
-// no point's `select.exist` matches. It cannot be shared with them — a
-// template ships standalone, outside this package — so it is written twice on
-// purpose, and both sides must move together.
 function ownPoint(points: any[]): any {
   let best = points[0]
 
   for (const pt of points) {
-    if (null == pt || null == pt.segments || null == best || null == best.segments) {
+    if (null == pt || null == pt.s || null == best || null == best.s) {
       continue
     }
 
@@ -254,7 +140,7 @@ function opParams(op: any): any[] {
   let points: any[] = op && op.points ? each(op.points) : []
 
   const canonical = points.filter((pt: any) =>
-    null == (pt && pt.select && pt.select['$action']))
+    null == (pt && pt.q && pt.q['$action']))
   if (0 < canonical.length) {
     points = canonical
   }
@@ -266,18 +152,17 @@ function opParams(op: any): any[] {
   points.forEach((pt: any, pointIndex: number) => {
     // Path AND query: a path-param-only read misses e.g. GET /result?trace_id=,
     // which has no path param at all but still addresses one record.
-    const pathParams = pt && pt.args && pt.args.params ? each(pt.args.params) : []
-    const queryParams = pt && pt.args && pt.args.query ? each(pt.args.query) : []
+    const pathParams = pt && pt.g && pt.g.params ? each(pt.g.params) : []
+    const queryParams = pt && pt.g && pt.g.query ? each(pt.g.query) : []
     const params = [...pathParams, ...queryParams]
     const requiredHere: Record<string, boolean> = {}
     params.forEach((p: any) => {
-      if (p && null != p.name) {
-        requiredHere[p.name] = false !== p.reqd
-        if (!seen[p.name]) {
-          seen[p.name] = { ...p }
-          // A param first seen on a later point was absent earlier: optional.
-          requiredOnAll[p.name] = 0 === pointIndex
-          out.push(seen[p.name])
+      if (p && null != p.n) {
+        requiredHere[p.n] = false !== p.r
+        if (!seen[p.n]) {
+          seen[p.n] = { ...p }
+          requiredOnAll[p.n] = 0 === pointIndex
+          out.push(seen[p.n])
         }
       }
     })
@@ -289,25 +174,10 @@ function opParams(op: any): any[] {
   })
 
   out.forEach((p: any) => {
-    p.reqd = true === requiredOnAll[p.name]
+    p.r = true === requiredOnAll[p.n]
   })
 
-  // Unrelated cross-references share no param, so the intersection came out
-  // empty and NOTHING is required — which generates a `load({})` that drops
-  // the id. Fall back to the entity's own point and take its params whole.
-  //
-  // Two guards, and both are load-bearing:
-  //
-  //   - only when the intersection produced nothing, so a genuine set of
-  //     alternative routes with a shared param still merges (a `page_id` on
-  //     every route stays required, per-route siblings stay optional);
-  //   - only when the points describe DIFFERENT routes. Points on one path
-  //     that differ solely by optional query params (`/users?email=` and
-  //     `/users?name=`) legitimately require nothing, and are not
-  //     cross-references — collapsing them to one point would drop the
-  //     other's fields from the generated request type, so a caller could
-  //     not express them at all.
-  if (1 < points.length && !out.some((p: any) => p.reqd) && !samePath(points)) {
+  if (1 < points.length && !out.some((p: any) => p.r) && !samePath(points)) {
     return opParams({ points: [ownPoint(points)] })
   }
 
@@ -315,30 +185,23 @@ function opParams(op: any): any[] {
 }
 
 
-// Does a field participate in an op? Absent op-entry -> participates; only an
-// explicit `active: false` excludes it.
 function fieldInOp(field: any, opname: string): boolean {
   const fop = field && field.op && field.op[opname]
   return null == fop || fop.active !== false
 }
 
 
-// Decide optionality for a field in a no-params request payload, per op.
 function fieldOptional(field: any, opname: string): boolean {
   switch (opname) {
     case 'create':
-      // Respect the model's required flag: required unless req === false.
-      return false === field.req
+      return false === field.r
     case 'update':
-      // Patch semantics — every field optional.
       return true
     case 'load':
     case 'remove':
-      // Best-effort key convention: the `id` field is required, rest optional.
-      return 'id' !== field.name
+      return 'id' !== field.n
     case 'list':
     default:
-      // Filter — every field optional.
       return true
   }
 }
@@ -355,46 +218,35 @@ function opRequestShape(ent: any, opname: string):
     return { items: [], fromParams: false }
   }
 
-  // Ops that carry a BODY are the exception to "op-declared params win":
-  // their request payload is BOTH. `PUT /v1/todo/item/{id}` declares the path
-  // param `id`, which the SDK resolves out of reqdata (see the param
-  // utility's reqmatch -> match -> reqdata search), while the fields the
-  // caller wants to change come from the entity. Params alone produced
-  // `<Name>UpdateData = { id }` — no way to send anything to update.
-  //
-  // The param stays in the payload because the path needs it; keeping it out
-  // of the request BODY is the model's job, via the op's `transform.req`
-  // (@voxgig/apidef restricts the body to a closed request schema's declared
-  // properties).
   const isbodyop = 'create' === opname || 'update' === opname || 'patch' === opname
 
   const params = opParams(op)
   if (0 < params.length && !isbodyop) {
     const items = params.map((p: any) => ({
-      name: p.name,
-      type: p.type,
-      optional: false === p.reqd,
+      name: p.n,
+      type: p.t,
+      optional: false === p.r,
     }))
     return { items, fromParams: true }
   }
 
   const paramItems = isbodyop ? params.map((p: any) => ({
-    name: p.name,
-    type: p.type,
-    optional: false === p.reqd,
+    name: p.n,
+    type: p.t,
+    optional: false === p.r,
   })) : []
   const paramNames = new Set(paramItems.map((p: any) => p.name))
 
   const fields = (ent.fields ? each(ent.fields) : [])
-    .filter((f: any) => f.active !== false)
+    .filter((f: any) => f.a !== false)
     .filter((f: any) => fieldInOp(f, opname))
 
   const items = paramItems.concat(
     fields
-      .filter((f: any) => !paramNames.has(f.name))
+      .filter((f: any) => !paramNames.has(f.n))
       .map((f: any) => ({
-        name: f.name,
-        type: f.type,
+        name: f.n,
+        type: f.t,
         optional: fieldOptional(f, opname),
       })))
 
@@ -402,13 +254,6 @@ function opRequestShape(ent: any, opname: string):
 }
 
 
-// The entity's id-like key field, or null when it has none. Used by the doc
-// generators to decide whether an example may key a load/remove on `{ id: ... }`
-// and access `.id` on a returned entity, OR must degrade to `load()` with no
-// argument (some APIs model an entity whose load match carries no id — e.g. a
-// response-wrapped spec, where AqiLoadMatch is { code, data, msg }). Prefers the
-// model's declared id field name, then a literal `id`, checking the load-match
-// shape first and the entity's own fields as a fallback.
 function entityIdField(ent: any): string | null {
   if (null == ent) {
     return null
@@ -460,29 +305,6 @@ function entityPrimaryOp(ent: any): string | null {
 }
 
 
-// Collision-free target-language CLASS name for an entity. The natural
-// class name is `<Name>Entity`, but that can equal another entity's
-// canonical DATA-type name `<Name'>` when Name' === Name + 'Entity' (e.g.
-// GitLab's `project` -> class `ProjectEntity` collides with `project_entity`
-// -> data type `ProjectEntity`), which redeclares a type in Go and merges/
-// shadows it in ts/py/rb. This assigns each entity a class name that is
-// unique across ALL emitted top-level type names (every entity's data type
-// and per-op Match/Data types, plus already-assigned class names): the
-// natural `<Name>Entity` when free, else `<Name>EntityClient`, `...Client2`,
-// … The DATA type keeps its canonical `<Name>` — only the suffixed class
-// yields. Deterministic (sorted-key iteration) and stable across runs.
-//
-// Covers EVERY entity, active or not: the consumer scaffold (create-sdkgen
-// Root.ts) iterates the RAW entity collection, and every EntityTypes_<lang>
-// emits with `only_active: false`, so an inactive entity still contributes a
-// generated data type AND still needs a class name. Filtering to actives here
-// left inactive entities on the un-deduped `<Name>Entity` fallback and left
-// their data types out of `taken` — so an ACTIVE entity's class could collide
-// with an INACTIVE entity's emitted data type (e.g. active `project` ->
-// class `ProjectEntity` vs inactive `project-entity` -> type `ProjectEntity`,
-// a redeclaration in Go).
-//
-// Memoised per entity-collection object so the O(n) assignment runs once.
 const _classNameCache = new WeakMap<object, Record<string, string>>()
 
 function entityClassNames(entityColl: any): Record<string, string> {
@@ -493,7 +315,6 @@ function entityClassNames(entityColl: any): Record<string, string> {
 
   const ents = deriveEntityNames(entityColl)
 
-  // 1. Every top-level DATA-type name the target emits.
   const taken: Record<string, boolean> = {}
   ents.forEach((e: any) => {
     taken[e.Name] = true
@@ -537,19 +358,6 @@ function entityClassName(ent: any, entityColl: any): string {
 }
 
 
-// Cross-entity TYPE-name collision detection. entityClassNames keeps CLASS
-// names collision-free, but the DATA/op type names are the raw `<Name>` /
-// opTypeName(...) — two entities whose PascalCase Name coincides (e.g.
-// `foo-bar` vs `foo_bar`), or a data-type name equal to another entity's
-// op-type name, emit DUPLICATE top-level type declarations: a redeclaration
-// compile error in go/rust/c/cpp/csharp and the JVM containers, silent
-// merging in ts. The names cannot be auto-renamed here — the generated
-// entity classes and op fragments reference them by token — so the guard
-// surfaces the collision loudly instead. Returns the sorted duplicate names
-// (empty when clean). `Name` is derived here (deriveEntityNames), so the
-// guard cannot be silently disabled by running before an emitter.
-//
-// Memoised per entity-collection object, like entityClassNames.
 const _typeCollisionCache = new WeakMap<object, string[]>()
 
 function entityTypeCollisions(entityColl: any): string[] {
@@ -594,14 +402,6 @@ function warnEntityTypeCollisions(entityColl: any, log: any, lang: string): stri
 }
 
 
-// Pick a representative entity for a single illustrative snippet (e.g. the
-// README's test-mode example): the first ACTIVE entity that exposes a read
-// op (list/load) so the snippet is meaningful, else the first with ANY
-// active op, else the first active entity. Returns { entity, primaryOp }
-// where primaryOp is null only when NO entity has an op — so callers never
-// fabricate an op the entity lacks (the cause of `.load()` on an op-less
-// entity like Cloudsmith's `Abort`). Entities iterate in sorted-key order
-// for deterministic output.
 function pickExampleEntity(entity: any): { entity: any, primaryOp: string | null } {
   const actives = each(entity).filter((e: any) => e && e.active !== false)
   const readable = actives.filter((e: any) => {
@@ -653,7 +453,7 @@ function medianOf(xs: number[]): number {
 }
 
 
-// The id field on the entity's DATA type (its fields[]), or null. DISTINCT from
+// The id field on the entity's DATA type (its fields{}), or null. DISTINCT from
 // entityIdField (the load-MATCH key): an API can model a load match that carries
 // an `id` param while the response entity itself has no `id` field, so `.id`
 // access on a RETURNED record must be guarded on this, not on the match key.
@@ -663,10 +463,10 @@ function entityDataIdField(ent: any): string | null {
   }
   const idName = (ent.id && ent.id.field) || 'id'
   const fields = ent.fields ? each(ent.fields) : []
-  if (fields.some((f: any) => f && f.name === idName)) {
+  if (fields.some((f: any) => f && f.n === idName)) {
     return idName
   }
-  if (fields.some((f: any) => f && f.name === 'id')) {
+  if (fields.some((f: any) => f && f.n === 'id')) {
     return 'id'
   }
   return null

package/src/helpers/optspec.ts

@@ -1,23 +1,3 @@
-// THE CLIENT OPTION SPEC, assembled from the model.
-//
-// One schema, not twenty. `main.kit.optspec` (model/sdkgen.aon) declares the
-// standard SDK options; each active feature's own `config.options` declares
-// its own. Both are already struct.validate specs in the by-example sense — a
-// concrete value is the type AND the default — so assembling them is a merge,
-// not a translation. The `Spec` component writes the result into the SDK and
-// makeOptions validates the caller's options against it.
-//
-// WHAT THIS REPLACES. Every language's make_options template carried its own
-// literal copy of the standard options (cpp and scala as JSON string
-// constants), and the feature half did not exist at all: the shipped spec was
-//
-//   feature: { `$CHILD`: { `$OPEN`: true, active: false } }
-//
-// so a feature's options were never checked and a typo in one was silently
-// ignored — `{ feature: { cache: { ttl: '5s' } } }` configured nothing and
-// said nothing. Meanwhile the README's option tables came from a THIRD place
-// (`target.options`, `feature.config.options`), which is how a documented
-// option and a validated option could be different sets.
 
 import { each } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
@@ -32,33 +12,11 @@ const S_ONE = sentinel('ONE')
 const S_NIL = sentinel('NIL')
 
 
-// A feature entry the caller may omit.
-//
-// WHY NOT A BARE MAP. A spec value is also the value validate INSERTS when
-// the key is absent, so naming every feature with a bare map would put an
-// entry for every feature the model declares into `options.feature` — and
-// `makeOptions` derives the feature ADD ORDER from that map's keys. The
-// `$ONE`/`$NIL` union keeps an absent feature absent and validates a supplied
-// one, which is the behaviour `$CHILD` had and the behaviour callers have.
 function optional(spec: any): any[] {
   return [S_ONE, spec, S_NIL]
 }
 
 
-// The spec for one feature's options.
-//
-// TWO DECLARATIONS, ONE SPEC:
-//   `config.options` — options WITH a default. Also the docs table.
-//   `config.optspec` — options with NO sensible default: callbacks (`sink`,
-//                      `now`, `idgen`), injected objects (`logger`), values
-//                      that only make sense when supplied. Declared as bare
-//                      sentinels, so they type-check without inventing a
-//                      default the feature would then have to ignore.
-//
-// OPEN BY DEFAULT. A feature may read an option neither list names — the
-// shipped set still does, which is why this is open rather than closed — and
-// rejecting those would break working clients on upgrade. `config.strict:
-// true` closes one feature's spec once its options are fully declared.
 function featureOptionSpec(feat: any): Record<string, any> {
   const config = (feat && feat.config) || {}
   const spec: Record<string, any> = {}
@@ -67,19 +25,8 @@ function featureOptionSpec(feat: any): Record<string, any> {
     spec[S_OPEN] = true
   }
 
-  // Every feature takes `active`, whatever else it declares. Stated rather
-  // than assumed: a feature whose model omits `config.options` entirely
-  // (nothing stops one) must still validate the one option it certainly has.
   spec.active = optionalSpec(byExampleSpec(false))
 
-  // EVERY FEATURE OPTION IS OPTIONAL, and that is not a policy choice here —
-  // it is what a caller does. `{ feature: { cost: { active: true, unit:
-  // 0.002 } } }` names two of cost's nine options and means the defaults for
-  // the other seven, which the feature's own code applies. A spec naming a
-  // key requires it, so without this widening cost's own corpus case failed
-  // its own feature's spec for the seven it did not mention.
-  //
-  // Widened to their KIND as well — see byExampleSpec.
   for (const [name, val] of Object.entries(config.options || {})) {
     spec[name] = optionalSpec(byExampleSpec(val))
   }
@@ -101,25 +48,11 @@ function featureOptionSpec(feat: any): Record<string, any> {
 // target must not validate against — or document — a feature it has no
 // implementation for. Without a name every active feature is included.
 function optionSpec(model: any, targetname?: string): Record<string, any> {
-  // `only_active: false` IS THE WHOLE SPEC. getModelPath filters out any
-  // child whose `active` is false, and a spec is full of them: `test: {
-  // active: false }`, the `$CHILD` entity template, every feature default.
-  // Filtered, the spec silently lost its `test` entry and validate then
-  // rejected a perfectly ordinary `{ test: { active: true } }` with
-  // "Unexpected keys at field <root>: test". This is a SCHEMA, not a set of
-  // things to emit — `active: false` here is a default value, not a switch.
   const base = getModelPath(model, `main.${KIT}.optspec`,
     { required: false, only_active: false }) || {}
 
-  // Cloned, because the model is shared across every target in one build and
-  // a spec assembled for `ts` must not be the object `js` then extends.
   const spec: Record<string, any> = JSON.parse(JSON.stringify(base))
 
-  // The generic entry, kept from the shipped spec: a feature supplied at
-  // construction through `extend` (the station adopt path) is not in the
-  // model, so its options must still pass. Named entries below are checked
-  // against their own spec; anything else gets `active` checked and the rest
-  // waved through.
   const feature: Record<string, any> = {
     [S_CHILD]: {
       [S_OPEN]: true,
@@ -141,16 +74,6 @@ function optionSpec(model: any, targetname?: string): Record<string, any> {
 }
 
 
-// The per-entity data/request specs a target needs, or null when it needs
-// none.
-//
-// GATED ON THE FEATURE, and that gate is the whole reason this returns null
-// rather than an empty map. The specs are derived data: every one of them can
-// be rebuilt from `fields[].type`, which the generated config already
-// carries. Emitting them unconditionally would grow every existing project's
-// generated source — and, above the config size threshold, flip targets from
-// the literal representation to the parsed-JSON one — to carry a spec nothing
-// reads. A project that turns `validate` on pays for it; nobody else does.
 function entitySpecMap(model: any, targetname?: string): Record<string, any> | null {
   const feats = targetFeatures(model, null == targetname ? undefined : targetname)
   const validate = (feats as any).validate