@voxgig/apidef 8.11.0 → 8.12.1

package/src/transform/flowstep.ts

@@ -11,23 +11,6 @@ import {
 } from '../utility'
 
 
-// Detect a path-parameter that is in fact the entity's own id, after URL
-// renaming. Three ways an identity can show up:
-//   1. The param literally has name 'id' (the common case for e.g. /things/{id}).
-//   2. The param's lower-camelCase name appears in `point.rename.param` mapping
-//      to 'id' — e.g. `{connectionId: 'id'}` for `/companies/{company_id}/connections/{id}`.
-//      In this case the param's own name is `connection_id` (apidef snake-cased
-//      it), which doesn't equal 'id' but the segment's `var` is 'id'.
-//   3. Positional convention: for singleton ops (load/update/remove), the
-//      LAST variable segment in the path is the entity's own id. Catches
-//      cases where the entity name and path placeholder differ in spelling
-//      (e.g. entity `enviroment` vs path `/environments/{environment_id}`)
-//      and apidef therefore didn't synthesize a rename-to-id.
-//
-// Without this helper, the flow generator double-counts the entity's id —
-// emitting it as both `srcdatavar.id` AND a separate body field — which the
-// in-memory test mock then requires to match a non-existent field on the
-// stored entity.
 function isEntityIdParam(point: any, param: any, opname?: string): boolean {
   if ('id' === param?.name) return true
   const renameMap = point?.rename?.param
@@ -79,8 +62,6 @@ const flowstepTransform: Transform = async function(
     const ent: ModelEntity = kit.entity[flow.entity]
     const opmap = ent.op
 
-    // TODO: spec parameter passed into each step func, used semantically by generator
-    // validation: part of spec, semantic name and params, up to generator how to use it
     const ref01 = ent.name + '_ref01'
 
     createStep(opmap, flow, ent, { input: { ref: ref01 } })
@@ -186,12 +167,6 @@ const createStep: MakeFlowStep = (
 
     each(point.args.params, (param: any) => {
       if ('id' === param.name) {
-        // For CREATE, `id` in the path is NOT the entity's own id (entity is
-        // being created here — its id doesn't exist yet). It's some parent's
-        // id renamed by apidef's path normalization (e.g. `space_id` → `id`
-        // in `/spaces/{id}/space_memberships` for SpaceMembership). Recover
-        // the original snake_case name so the test seeds the parent's id
-        // into both the created entity's data AND the URL.
         const origName = originalSnakeNameOfRenamedId(point)
         if (origName) {
           step.match[origName] = args.input?.[origName] ?? origName.replace(/_id/, '') + '01'
@@ -203,12 +178,6 @@ const createStep: MakeFlowStep = (
       step.match[param.name] = args.input?.[param.name] ?? param.name.replace(/_id/, '') + '01'
     })
 
-    // Also seed any path-param fields required by other ops (typically LIST
-    // through a sibling parent path), so the in-memory test mock can find
-    // the just-created entity when a later step queries by those fields.
-    // Without this, a metric created at /pages/{page_id}/metrics/data lacks
-    // the page_access_user_id field required by
-    // /pages/{page_id}/page_access_users/{page_access_user_id}/metrics LIST.
     seedRelatedOpParams(opmap, point, step)
 
     flow.step.push(step)
@@ -227,8 +196,6 @@ function seedRelatedOpParams(opmap: any, createPoint: any, step: ModelEntityFlow
         if (!param?.name) continue
         if (isEntityIdParam(point, param, opname as any)) continue
         if (step.match[param.name] !== undefined) continue
-        // For renamed-from-id params on CREATE's chosen point we'd already
-        // have set the snake-case origin; don't double-write.
         if ('id' === param.name) continue
         step.match[param.name] =
           param.name.replace(/_id/, '') + '01'
@@ -251,10 +218,6 @@ const listStep: MakeFlowStep = (
 
     each(point.args.params, (param: any) => {
       if ('id' === param.name) {
-        // For LIST, `id` in the path is a parent's id renamed by apidef
-        // (LIST doesn't address a single entity by id). Recover the original
-        // snake_case name so test code references a real idmap entry rather
-        // than landing on the bogus `id01` default.
         const origName = originalSnakeNameOfRenamedId(point)
         if (origName) {
           step.match[origName] = args.input?.[origName] ?? origName.replace(/_id/, '') + '01'
@@ -348,18 +311,6 @@ const removeStep: MakeFlowStep = (
 }
 
 
-// The field the generated basic-flow test WRITES, to prove an update took
-// effect. It must not be a route parameter of the update itself.
-//
-// The test mock builds its lookup selector out of the request data, so when
-// the marked field is also a path segment the selector asks for the record by
-// the value it is about to write — it matches nothing and the mock answers
-// 404, on a flow that is doing exactly what it was told to.
-//
-// trello's notification_channel_setting chose `channel`, the {channel} of
-// PUT /members/{member_id}/notificationsChannelSettings/{channel}, and its js,
-// php and ts suites all failed on it. Updating a routing key is a rename, not
-// a field update, and neither the mock nor the SDK models it as one.
 function firstTextField(ent: ModelEntity, op?: ModelOp) {
   const paramNames: Record<string, boolean> = {}
   each((op as any)?.points).forEach((pt: any) => {

package/src/transform/graphql.ts

@@ -1,18 +1,5 @@
 /* Copyright (c) 2024-2026 Voxgig, MIT License */
 
-// Render the GraphQL wire data onto each point: the complete operation
-// document, its variable bindings, the response unwrap path, and (for list
-// ops) the pagination descriptor.
-//
-// Documents are computed HERE, once, and stored in the model as strings.
-// The alternative — shipping structured selection data and assembling query
-// text inside every generated SDK — would mean one query assembler per
-// language target, all of which must stay semantically identical. One
-// renderer in apidef is the whole reason GraphQL support stays affordable
-// across the target matrix.
-//
-// Documents are rendered SINGLE-LINE with sorted selection fields, so the
-// emitted model is byte-stable and schema drift shows up in model diffs.
 
 import { each } from 'jostraca'
 
@@ -33,9 +20,6 @@ import type {
 import { deriveRetShape } from '../guide/graphql01'
 
 
-// Fields the default fragment never selects on a to-one relation: the stub
-// carries the id only, so the caller loads the related entity through its
-// own entity op.
 const REL_STUB = '{ id }'
 
 
@@ -108,9 +92,6 @@ function payloadScalarFields(typeName: string, def: any): string[] {
 }
 
 
-// Variable bindings for a root field: one per argument. `from` is the op
-// argument the value is read from; for the input-object argument that is the
-// request data itself.
 function buildVars(fielddef: any, def: any): ModelGraphqlVar[] {
   const args = fielddef?.args ?? []
 
@@ -139,7 +120,6 @@ function buildVars(fielddef: any, def: any): ModelGraphqlVar[] {
 }
 
 
-// `issue(id: $id, first: $first)` — argument list wired to variables.
 function argList(vars: ModelGraphqlVar[]): string {
   return 0 === vars.length ? '' :
     '(' + vars.map((v) => v.name + ': $' + v.name).join(', ') + ')'
@@ -158,7 +138,6 @@ function varDecl(vars: ModelGraphqlVar[]): string {
 }
 
 
-// Render one operation document, single-line.
 function renderDoc(
   opname: string,
   optype: string,
@@ -176,7 +155,6 @@ function renderDoc(
       ' fragment ' + fragName + ' on ' + fragType +
       ' { ' + fragFields.join(' ') + ' }' : '')
 
-  // Collapse any accidental double spacing so the string is canonical.
   return doc.replace(/\s+/g, ' ').trim()
 }
 
@@ -220,7 +198,6 @@ const graphqlTransform: Transform = async function(
 
         const vars = buildVars(fielddef, def)
 
-        // Selection shape and response unwrap both follow the return kind.
         let selection = fragSpread
         let respath = 'body.data.' + rootfield
 
@@ -235,12 +212,6 @@ const graphqlTransform: Transform = async function(
           selection = fragSpread
         }
         else if ('payload' === ret.kind && null == ret.entity) {
-          // Entity-less payload: Linear's DeletePayload is entityId +
-          // success + lastSyncId and nothing else. The classifier admits
-          // these (the entity comes from the field name), so the renderer
-          // must not fall through to the default `{ id }` spread — the
-          // payload HAS no id, and the server rejects the whole document.
-          // Select the payload's own scalars and unwrap to the payload.
           const own = payloadScalarFields(fielddef.type, def)
           selection = '{ ' + (0 < own.length ? own.join(' ') : '__typename') + ' }'
           respath = 'body.data.' + rootfield
@@ -256,17 +227,10 @@ const graphqlTransform: Transform = async function(
           respath = 'body.data.' + rootfield + '.' + ret.unwrap
         }
 
-        // Distinct operation name per point. The action comes from the GUIDE,
-        // not from mpoint.select: selectTransform runs after this stage, so
-        // $action is not set yet, and without the suffix every action point
-        // on an op would ship the same operation name (three PlanetUpdates),
-        // which is what server logs, tracing and APM key on.
         const actionName = Object.keys((gfield as any)?.action ?? {})[0]
         const docname = pascal(entname) + pascal(opname) +
           (null != actionName ? pascal(actionName) : '')
 
-        // GraphQL points ride the HTTP machinery: POST to the single
-        // endpoint, no path segments. The document carries everything else.
         mpoint.kind = 'graphql'
         mpoint.method = 'POST'
         mpoint.segments = []

package/src/transform/operation.ts

@@ -79,7 +79,6 @@ function collectOps(ctx: any, gent: GuideEntity) {
   ; (gent as any).opm$ = (gent as any).opm$ ?? {}
   each((gent as any).paths$, (pathdesc: PathDesc) => {
     each(pathdesc.op, (gop: GuidePathOp, opname: OpName) => {
-      // Op-level opt-out; see the entity-level note in transform/entity.ts.
       if (!guideActive(gop)) {
         return
       }
@@ -152,15 +151,6 @@ function resolveRemove(opm: ModelOpMap, gent: GuideEntity): undefined | ModelOp
 function resolvePatch(opm: ModelOpMap, gent: GuideEntity): undefined | ModelOp {
   const opdesc = resolveOp('patch', gent)
 
-  // If patch is actually update, make it update!
-  //
-  // That holds when there is no PUT update at all, and equally when every
-  // PUT update point is an ACTION: a verb such as GitHub's `merge` borrows
-  // the update slot (actions have no slot of their own) but is not the
-  // entity's update. Leaving PATCH as `patch` there made the real update
-  // unreachable, since no target emits a `patch` method, and routed a plain
-  // update() to the verb. The action points join the promoted PATCH, and
-  // `$action` selects them at call time.
   if (null != opdesc && (null == opm.update || onlyActionPaths(gent, 'update'))) {
     if (null != opm.update) {
       opdesc.points.push(...opm.update.points)
@@ -191,13 +181,6 @@ function resolveOp(opname: OpName, gent: GuideEntity): undefined | ModelOp {
     mop = {
       name: opname,
       points: opdesc.paths.map((p: PathDesc) => {
-        // Renames already applied by entity.ts resolvePathList — re-applying
-        // here corrupted paths for any spec where rename map maps an old
-        // name to a value that another rename maps to a different new name
-        // (e.g. gitlab `/groups/{id}/badges/{badge_id}` with rename
-        // `{badge_id: 'id', id: 'project_id'}` ended up as
-        // `/groups/{project_id}/badges/{project_id}` — the second pass
-        // rewrote the freshly-renamed `{id}` into `{project_id}` again).
         const segments = p.segments
 
         const mpoint: ModelPoint = {
@@ -206,12 +189,6 @@ function resolveOp(opname: OpName, gent: GuideEntity): undefined | ModelOp {
           rename: p.rename,
           method: p.method,
           args: {},
-          // Carry the per-path op transform (res `body.<entity>`, req
-          // `{<entity>: reqdata}`) computed by the guide step
-          // (heuristic01 ResolveTransform) onto the point. It lives on the
-          // path's op, not on the op-map entry, so read p.op.transform.
-          // Spread into a fresh object so the default-fill below never
-          // mutates the shared guide op.transform across points.
           transform: { ...((p as any).op?.transform ?? {}) },
           select: {
             exist: []

package/src/transform/top.ts

@@ -14,7 +14,6 @@ import type {
 } from '../types'
 
 import type {
-  // GuidePath,
   PathDesc,
   OpDesc,
 } from '../desc'
@@ -24,19 +23,9 @@ import type {
 } from '../model'
 
 
-// Guide* => from guide model
-// *Desc => internal working descriptiuon
-// *Def => API spec definition
-// Model* => Generated SDK Model
 
 
-// type GuideEntity = {
-//   name: string,
-//   path: Record<string, GuidePath>
 
-//   paths$: PathDesc[]
-//   opm$: Record<OpName, OpDesc>
-// }
 
 
 const topTransform = async function(
@@ -55,14 +44,6 @@ const topTransform = async function(
   // the docs generated from it) never carry an empty/degenerate description.
   kit.info.description = ensureDescription(kit.info)
 
-  // Public APIs that declare NO authentication (no security schemes, no
-  // top-level `security`, and no per-operation `security`) get an explicit
-  // no-auth signal in the model. Downstream sdkgen reads it via
-  // isAuthActive() (main.kit.info.auth === false) to suppress apikey/auth
-  // code, docs and examples. Only the negative signal is emitted: when the
-  // spec DOES declare auth we leave `auth` unset so the SDK's own config
-  // (main.kit.config.auth) governs. Set AFTER stringifyInfoScalars so the
-  // value stays a real boolean rather than the string "false".
   if (true === def.graphql) {
     // A GraphQL schema NEVER declares HTTP auth, so specDeclaresAuth would
     // report every secured GraphQL API (Linear included) as public and
@@ -80,8 +61,6 @@ const topTransform = async function(
           type: authopt.type ?? 'apiKey',
           in: authopt.in ?? 'header',
           name: authopt.name ?? 'Authorization',
-          // '' means a raw credential with no prefix (Linear's style);
-          // prepareAuth in generated SDKs already honours that.
           prefix: authopt.prefix ?? '',
         }
       }
@@ -98,12 +77,6 @@ const topTransform = async function(
     if (null != security) {
       kit.info.security = security
 
-      // Record the ACCESS-TOKEN EXCHANGE, when the spec describes one. The
-      // endpoint that issues credentials is not a resource and does not
-      // become an entity (the guide deactivates it — see
-      // guide/heuristic01.ts and ADR-002); these facts are how it survives
-      // into the model instead, and they are exactly what sdkgen's
-      // `secrets` feature needs to drive the exchange.
       const exchange = findAuthExchange(def)
       if (null != exchange) {
         kit.info.security.exchange = exchange
@@ -111,7 +84,6 @@ const topTransform = async function(
     }
   }
 
-  // Swagger 2.0
   if (def.host) {
     kit.info.servers.push({
       url: (def.schemes?.[0] ?? 'https') + '://' + join([def.host, def.basePath], '/', true)
@@ -127,25 +99,15 @@ const topTransform = async function(
     if (!server || 'string' !== typeof server.url) continue
     const url: string = server.url.trim()
     if (url === '') continue
-    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) continue   // already has scheme
-    // `//host/path` is a protocol-relative URL — meaningless to a
-    // backend SDK, treat as missing-scheme and default to https.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) continue
     if (url.startsWith('//')) {
       server.url = 'https:' + url
       continue
     }
-    // `/path` is path-only (relative to wherever the spec is served).
-    // Leave it untouched; it's a valid OpenAPI form.
     if (url.startsWith('/')) continue
     server.url = 'https://' + url
   }
 
-  // A usable SDK requires a base URL. OpenAPI 3 puts it in `servers[].url`;
-  // Swagger 2 derives it from `host` + `basePath`. If neither yields a
-  // non-empty url, the generated SDK has no way to issue requests, so fail
-  // the apidef model build rather than emit broken code.
-  // (For GraphQL the parser already synthesised servers[0] from the required
-  // `endpoint` build option, so this check passes on the same terms.)
   const firstServerUrl: any = kit.info.servers?.[0]?.url
   if (null == firstServerUrl || '' === String(firstServerUrl).trim()) {
     throw new Error(
@@ -156,8 +118,6 @@ const topTransform = async function(
     )
   }
 
-  // A short "what this API is" blurb and a canonical website link, for doc
-  // generators. Only set when derivable, so downstream can gate on them.
   const summary = resolveSummary(def)
   if (null != summary) {
     kit.info.summary = summary
@@ -171,8 +131,6 @@ const topTransform = async function(
 }
 
 
-// True when the text carries at least one alphabetic character — i.e. it is
-// real prose rather than a placeholder like "." / "---" / whitespace.
 function hasLetters(text: string): boolean {
   return /[a-zA-Z]/.test(text)
 }
@@ -210,22 +168,18 @@ function resolveSummary(def: any): string | undefined {
   }
 
   const desc = 'string' === typeof info.description ? info.description : ''
-  // Treat letterless prose (a bare "." placeholder, "---", …) as no summary
-  // rather than surfacing it verbatim.
   if ('' === desc.trim() || !hasLetters(desc)) {
     return undefined
   }
 
   const lines = desc.split('\n')
   let i = 0
-  // Skip leading blank lines, ATX headings (`# ...`) and setext underlines.
   while (i < lines.length &&
     ('' === lines[i].trim() ||
       /^\s*#{1,6}\s/.test(lines[i]) ||
       /^\s*(-{2,}|={2,})\s*$/.test(lines[i]))) {
     i++
   }
-  // Take the first paragraph (up to the next blank line or heading).
   const para: string[] = []
   while (i < lines.length &&
     '' !== lines[i].trim() &&
@@ -238,12 +192,6 @@ function resolveSummary(def: any): string | undefined {
 }
 
 
-// A canonical link back to the API's own website, in priority order:
-//   1. externalDocs.url          (the spec's explicit external link)
-//   2. info['x-logo'].href       (redoc homepage link)
-//   3. homepage from the server  (strip an api./developer./docs. subdomain)
-//   4. info.contact.url
-//   5. info.termsOfService
 function resolveWebsite(def: any, servers: any[]): string | undefined {
   const info = def?.info ?? {}
 
@@ -272,15 +220,6 @@ function homepageFromServer(url: any): string | undefined {
     const u = new URL(url.includes('://') ? url : 'https://' + url)
     let host = u.hostname
     if ('' === host || !host.includes('.')) return undefined
-    // A templated server — `https://{instance}.dreamapply.com/api`, a per-tenant
-    // API declaring `instance` as an OpenAPI server variable — is a legitimate
-    // spec, but its host is not a resolvable address. Deriving a "website" from
-    // it put `https://{instance}.dreamapply.com` into the README as a clickable
-    // link that no browser can open. The URL parser accepts the braces, so the
-    // placeholder has to be rejected explicitly.
-    //
-    // Only the WEBSITE is skipped: the server URL itself is still emitted, where
-    // the variable is meaningful and the runtime substitutes it.
     if (/[{}]/.test(host)) return undefined
     host = host.replace(
       /^(api|api-[a-z0-9]+|apis|developer|developers|docs?|www)\./i, '')
@@ -297,24 +236,6 @@ function isHttpUrl(v: any): boolean {
 }
 
 
-// Describe the spec's PRIMARY security scheme as model facts
-// (info.security): scheme key, type, where the credential goes (in/name),
-// and the value prefix for Authorization-header credentials. The primary
-// scheme is the one named by the first top-level `security` requirement,
-// falling back to the first declared scheme. Returns null when nothing
-// usable is declared (the no-auth signal is handled separately).
-//
-// Prefix rules:
-//   http basic/bearer      -> 'Basic' / 'Bearer'
-//   oauth2 / openIdConnect -> 'Bearer' (access token in Authorization)
-//   apiKey in an Authorization header -> the prefix the API's own prose
-//     documents (e.g. `Authorization: OAuth <key>`), else '' (raw). An
-//     `apiKey` scheme means "send the credential as-is" — a `Bearer`/etc.
-//     prefix is only implied by an `http`+`bearer` scheme or explicit
-//     prose, so absent evidence the key goes in raw (e.g. The SMS Works'
-//     `Authorization: <jwt>`). A user override is available via
-//     config.auth.prefix.
-//   apiKey in any other header/query/cookie -> '' (raw credential)
 function resolveSecurity(def: any): Record<string, string> | null {
   const schemes: Record<string, any> =
     def.components?.securitySchemes ?? def.securityDefinitions ?? {}
@@ -344,8 +265,6 @@ function resolveSecurity(def: any): Record<string, string> | null {
   }
 
   if ('http' === type) {
-    // Swagger 2 `type: basic` has no `scheme`; OpenAPI 3 uses
-    // `scheme: basic|bearer|...`.
     out.prefix = 'basic' === String(scheme.scheme ?? '').toLowerCase() ?
       'Basic' : 'Bearer'
   }
@@ -367,25 +286,12 @@ function resolveSecurity(def: any): Record<string, string> | null {
         findAuthPrefix(def.info?.description) ??
         ''
     }
-    // else: raw credential in a named header/query/cookie — no prefix.
   }
 
   return out
 }
 
 
-// Find the spec's access-token exchange and describe it as model facts:
-// where it lives, and the field names it sends and answers with. Returns
-// null when the spec describes no exchange, which is the common case.
-//
-// `path` is RELATIVE to the server URL, with no leading slash, because the
-// server URL already carries whatever account or tenant segment the API
-// templates into it — an absolute path would drop that segment. sdkgen's
-// secrets feature resolves it against `options.base` for the same reason.
-//
-// Only the FIRST exchange is recorded. A spec describing two token
-// endpoints is describing two auth schemes, which is a bigger thing than a
-// field on info.security and is not guessed at here.
 function findAuthExchange(def: any): Record<string, string> | null {
   const secured = specSecuredByDefault(def)
   if (!secured) {
@@ -418,18 +324,6 @@ function findAuthExchange(def: any): Record<string, string> | null {
 }
 
 
-// Extract the credential prefix from a securityScheme's / info prose.
-// Three signals, in confidence order:
-//   1. An explicit `Authorization: <prefix> <cred>` line (any prefix word)
-//      — e.g. Statuspage's `Authorization: OAuth 89a2...`. The prefix must
-//      be a short word followed by something credential-shaped (a long
-//      token, or a `<key>` / `{token}` / `$KEY` / `YOUR_...` placeholder),
-//      so a bare `Authorization: 89a2...` doesn't match.
-//   2. A KNOWN scheme word (Bearer/OAuth/Token/Basic) shown as an example
-//      prefix — `Example: Bearer eyJ...` (NoFrixion's shape).
-//   3. A KNOWN scheme word named as the scheme — `the Bearer scheme`,
-//      `Bearer authentication`.
-// Returns null when nothing indicates a prefix (an apiKey then goes in raw).
 function findAuthPrefix(text: unknown): string | null {
   if ('string' !== typeof text || '' === text) {
     return null
@@ -441,14 +335,12 @@ function findAuthPrefix(text: unknown): string | null {
     return explicit[1]
   }
 
-  // A known scheme word as an example prefix, then a credential-shaped tail.
   const example = text.match(
     /(?:example|e\.g\.)[:\s][^\n]{0,20}?\b(Bearer|OAuth2?|Token|Basic)\b[ \t]+(?:<[^>\n]+>|\{[^}\n]+\}|[A-Za-z0-9._~+/=-]{6,})/i)
   if (null != example) {
     return canonAuthScheme(example[1])
   }
 
-  // A known scheme word named as the auth scheme.
   const named = text.match(
     /\b(Bearer|OAuth2?|Token|Basic)\b[ \t]+(?:scheme|authentication|auth\b|credentials?)/i)
   if (null != named) {
@@ -459,7 +351,6 @@ function findAuthPrefix(text: unknown): string | null {
 }
 
 
-// Canonical casing for a known scheme word (Bearer/OAuth/Token/Basic).
 function canonAuthScheme(word: string): string {
   const w = word.toLowerCase()
   if (w.startsWith('oauth')) return 'OAuth'
@@ -470,27 +361,18 @@ function canonAuthScheme(word: string): string {
 }
 
 
-// Does the spec declare any authentication? True if it defines security
-// schemes (OpenAPI 3 `components.securitySchemes` or Swagger 2
-// `securityDefinitions`), a top-level `security` requirement, or a
-// per-operation `security` requirement. Used to emit a no-auth signal
-// (info.auth: false) for fully public APIs.
 function specDeclaresAuth(def: any): boolean {
   if (null == def || 'object' !== typeof def) return false
 
   const nonEmptyObj = (v: any) =>
     null != v && 'object' === typeof v && Object.keys(v).length > 0
 
-  // OpenAPI 3 security schemes.
   if (nonEmptyObj(def.components?.securitySchemes)) return true
 
-  // Swagger 2 security definitions.
   if (nonEmptyObj(def.securityDefinitions)) return true
 
-  // Top-level security requirement.
   if (Array.isArray(def.security) && def.security.length > 0) return true
 
-  // Per-operation security requirement.
   const paths = def.paths
   if (paths && 'object' === typeof paths) {
     for (const pathItem of Object.values(paths)) {
@@ -508,13 +390,6 @@ function specDeclaresAuth(def: any): boolean {
 }
 
 
-// OpenAPI's `info` object (and the `servers` array) declares every scalar
-// leaf as a string. YAML/JSON parsers don't enforce that — `version: 2`
-// without quotes parses as the number 2, `version: true` as a boolean.
-// Apidef's downstream schema (apidef.aontu) unifies info fields as
-// `string`, so non-string scalars cause an aontu unify failure during
-// model resolution. Normalise scalar leaves to strings here, at the
-// model-build boundary, rather than relax the schema.
 function stringifyInfoScalars(node: any): any {
   if (null == node) return node
   if (Array.isArray(node)) return node.map(stringifyInfoScalars)
@@ -541,8 +416,3 @@ export {
   homepageFromServer,
   findAuthPrefix,
 }
-
-
-// export type {
-//   GuideEntity,
-// }

package/src/transform.ts

@@ -13,7 +13,6 @@ import { operationTransform } from './transform/operation'
 import { argsTransform } from './transform/args'
 import { selectTransform } from './transform/select'
 import { fieldTransform } from './transform/field'
-// import { manualTransform } from './transform/manual'
 
 
 

package/src/types.ts

@@ -5,6 +5,8 @@ import * as Fs from 'node:fs'
 import { Pino, prettyPino } from '@voxgig/util'
 import { Shape, Open, Any } from 'shape'
 
+import type { ResolvedSpec } from './resolved'
+
 
 const KIT = 'kit'
 
@@ -50,7 +52,6 @@ type ApiDefOptions = {
 }
 
 
-// Input definition format.
 type DefKind = 'OpenAPI' | 'GraphQL'
 
 
@@ -208,6 +209,8 @@ type ApiDefContext = {
   warn: any,
   metrics: Metrics,
   work: Record<string, any>
+
+  resolved?: ResolvedSpec
 }
 
 
@@ -237,7 +240,6 @@ type GuideControl = {}
 type GuideMetrics = {
   count: {
     path: number
-    // Schema root fields classified (GraphQL guides; 0 for OpenAPI).
     field: number
     method: number
     entity: number
@@ -253,15 +255,6 @@ type GuideMetrics = {
 
 
 type GuideEntity = {
-  // COMPOSITE IDENTITY CORRECTION, the guide's say over how an entity is
-  // addressed. apidef infers a compound key from adjacent path parameters,
-  // which is right far more often than not and cannot always be right:
-  // `/…/artifacts/{artifact_id}/{archive_format}` reads as composite and is
-  // not. Stating it here is the documented correction surface (ADR-002).
-  //
-  // `parts` names the compound key outright; `composite: false` says these
-  // adjacent parameters are not one (the record still has a key); `sep`
-  // changes the separator without restating the parts.
   id?: {
     parts?: string[]
     sep?: string
@@ -281,8 +274,6 @@ type GuideEntity = {
   // Why the heuristic deactivated it, so guide.aon reads as a record of a
   // decision rather than an unexplained `active: false`.
   why_inactive?: string
-  // GraphQL guides key operations by schema root field instead of path;
-  // the two branches are mutually exclusive per guide.
   field?: Record<string, GuidePath>
   path: Record<string, GuidePath>
 }