@voxgig/apidef 6.3.7 → 6.3.8

package/src/guide/heuristic01.ts

@@ -7,6 +7,8 @@ import { each } from 'jostraca'
 
 import { size, merge, getelem, isempty, items, keysof } from '@voxgig/struct'
 
+import { isEntityWrapperProp, envelopeProp, closedBodyTransform } from '../utility'
+
 
 import {
   ApiDefContext,
@@ -1126,17 +1128,48 @@ function ResolveTransform(spec: TaskSpec) {
     else if (isEntityWrapperProp(resprops[entdesc.name])) {
       transform.res = '`body.' + entdesc.name + '`'
     }
+    else {
+      // The wrapper is often named for the CARDINALITY rather than the
+      // entity — `{item: {...}}` from a load, `{items: [...]}` from a list —
+      // which the entity-name rules above cannot see. Left unwrapped, list()
+      // hands back the envelope where the caller expects an array, and the
+      // envelope key is mistaken for a field of the entity.
+      const envelope = envelopeProp(resprops, opname)
+      if (null != envelope) {
+        transform.res = '`body.' + envelope + '`'
+      }
+    }
   }
 
-  const reqprops = getRequestBodySchema(mdesc.requestBody)
+  // The SCHEMA is what closedBodyTransform needs (it reads
+  // additionalProperties); the wrapper-name checks need its PROPERTIES. They
+  // used to share one value and index the schema itself, so
+  // `schema['todoitem']` was always undefined and the entity-name request
+  // envelope was never detected — while the Go port read `.properties` and
+  // did detect it. That divergence was inert only because `req` was never
+  // serialised; now that it is, the two implementations would emit different
+  // request bodies for the same spec.
+  const reqschema = getRequestBodySchema(mdesc.requestBody)
+  const reqprops = reqschema?.properties
   debugpath(pathStr, methodName, 'TRANSFORM-REQ', keysof(reqprops))
-  if (reqprops) {
-    if (reqprops[entdesc.origname]) {
+  if (reqschema) {
+    if (null != reqprops?.[entdesc.origname]) {
       transform.req = { [entdesc.origname]: '`reqdata`' }
     }
-    else if (reqprops[entdesc.name]) {
+    else if (null != reqprops?.[entdesc.name]) {
       transform.req = { [entdesc.name]: '`reqdata`' }
     }
+    else {
+      // A CLOSED body schema names every property the server will accept, so
+      // the body is those properties — not the whole request payload. The
+      // payload also carries the op's PATH params (`id` for
+      // `PUT /item/{id}`), and a closed shape rejects the entire request over
+      // that one extra key: every update came back 400 with `invalid-data`.
+      const body = closedBodyTransform(reqschema)
+      if (null != body) {
+        transform.req = body
+      }
+    }
   }
 
   if (!isempty(transform) && null != op[opname]) {
@@ -1365,30 +1398,6 @@ function getResponseSchema(response: any) {
 }
 
 
-// A response property only "wraps" the entity when it is itself a structured
-// value that could contain the entity: an object, an array, a $ref, or a
-// composed (allOf/oneOf/anyOf) schema. A scalar property (string, integer,
-// number, boolean) that merely shares the entity's name is a field of the
-// entity, not a wrapper, so the response must not be unwrapped down to it.
-function isEntityWrapperProp(propSchema: any): boolean {
-  if (null == propSchema || 'object' !== typeof propSchema) {
-    return false
-  }
-  if (null != propSchema.$ref) {
-    return true
-  }
-  if (null != propSchema.properties ||
-    null != propSchema.items ||
-    null != propSchema.allOf ||
-    null != propSchema.oneOf ||
-    null != propSchema.anyOf) {
-    return true
-  }
-  const t = propSchema.type
-  return 'object' === t || 'array' === t
-}
-
-
 function inferEntityName(
   mdesc: any,
   parts: string[],

package/src/parse.ts

@@ -1,14 +1,15 @@
 /* Copyright (c) 2024-2025 Voxgig, MIT License */
 
-import { Jsonic } from 'jsonic'
-import { Yaml } from '@jsonic/yaml'
-
-import { decircular } from '@voxgig/util'
+import { Jsonic } from '@tabnas/jsonic'
+import { Yaml } from '@tabnas/yaml'
 
 import { relativizePath } from './utility'
 
 
-const yamlParser = Jsonic.make().use(Yaml)
+// NOTE: @tabnas/yaml types its Plugin against @tabnas/parser, while
+// Jsonic.use expects @tabnas/jsonic's own (structurally identical) Plugin
+// type - hence the cast.
+const yamlParser = Jsonic.make().use(Yaml as any)
 
 // Matches any line that is not purely a YAML comment or whitespace.
 const RE_HAS_CONTENT = /^\s*[^#\s]/m
@@ -100,12 +101,80 @@ async function parseOpenAPI(source: any, _meta?: any) {
   // Single-pass: add x-ref properties and resolve $ref pointers together.
   addXRefsAndResolve(parsed, parsed)
 
-  const def = decircular(parsed)
+  const def = decycle(parsed)
 
   return def
 }
 
 
+// Break reference cycles so the parsed spec stays JSON-serializable, WITHOUT
+// destroying the structure sharing that $ref inlining deliberately creates.
+//
+// @voxgig/util's decircular() rebuilds the tree — it allocates a fresh object
+// per *visit*, so a component reachable by k distinct paths is copied k times
+// and the result is the tree-expansion of the DAG, size O(fanout^depth). That
+// is catastrophic on exactly the shape real specs have (components reused
+// across nesting levels): a 2.3 KB spec with 12 levels and 3 refs per level
+// expanded to a 172 MB model, and 13 levels exhausted a 2 GB heap.
+//
+// Cycles are real here — inlining a self-referential schema makes the copy's
+// `properties` the same object as the original's, so the copy contains
+// itself — so they still have to be cut. This does it in place: only the edge
+// that closes a cycle is replaced (with decircular's marker string, so the
+// output shape is unchanged), every other node is visited exactly once and
+// left shared. Linear in the number of distinct nodes.
+function decycle(root: any) {
+  // Entry path of each node on the current ancestor chain; presence in this
+  // map is what identifies a back-edge. Nodes are removed on the way out, so
+  // a node reachable twice as a *sibling* is not treated as a cycle.
+  const onPath = new Map<any, string[]>()
+  // Fully-processed nodes. Revisiting one is legitimate sharing, not a cycle,
+  // and must not be walked (or copied) again.
+  const done = new WeakSet<any>()
+  const path: string[] = []
+
+  const walk = (node: any) => {
+    if (null == node || 'object' !== typeof node) return
+    if (done.has(node)) return
+
+    // The YAML parser hands back null-prototype objects. decircular() used to
+    // launder them into plain objects as a side effect of rebuilding the tree;
+    // parse()'s result is public, so keep that contract (callers reasonably
+    // expect `hasOwnProperty` etc. on a parsed spec) rather than leaking the
+    // parser's internal shape now that nothing is rebuilt.
+    if (!Array.isArray(node) && null === Object.getPrototypeOf(node)) {
+      Object.setPrototypeOf(node, Object.prototype)
+    }
+
+    onPath.set(node, path.slice())
+
+    const keys = Array.isArray(node) ?
+      node.map((_: any, i: number) => i) : Object.keys(node)
+
+    for (const key of keys as any[]) {
+      const val = node[key]
+      if (null == val || 'object' !== typeof val) continue
+
+      const cyclePath = onPath.get(val)
+      if (undefined !== cyclePath) {
+        node[key] = `[Circular *${cyclePath.join('.')}]`
+        continue
+      }
+
+      path.push(String(key))
+      walk(val)
+      path.pop()
+    }
+
+    onPath.delete(node)
+    done.add(node)
+  }
+
+  walk(root)
+  return root
+}
+
+
 // Single-pass tree walk that:
 // 1. Preserves original $ref values as x-ref
 // 2. Resolves $ref JSON pointers in-place
@@ -117,6 +186,20 @@ async function parseOpenAPI(source: any, _meta?: any) {
 // across every site that referenced the same component. (A deep clone is
 // deliberately avoided: schemas can be self-referential, which would make
 // cloning non-terminating.)
+// Keywords sitting beside a `$ref` on the *referring* node. OpenAPI 3.1 and
+// JSON Schema 2020-12 both allow them (`description`, `required`,
+// constraints, ...) and they still apply, so inlining must not drop them.
+// Applied over the resolved target, so the local statement wins.
+function refSiblings(node: any): any {
+  const out: any = {}
+  for (const k of Object.keys(node)) {
+    if ('$ref' === k) continue
+    out[k] = node[k]
+  }
+  return out
+}
+
+
 function addXRefsAndResolve(obj: any, root: any, visited?: WeakSet<any>) {
   if (!obj || typeof obj !== 'object') return
   if (!visited) visited = new WeakSet()
@@ -131,7 +214,7 @@ function addXRefsAndResolve(obj: any, root: any, visited?: WeakSet<any>) {
           const xref = item.$ref
           const resolved = resolvePointer(root, xref)
           if (resolved !== undefined) {
-            obj[i] = { ...resolved, 'x-ref': xref }
+            obj[i] = { ...resolved, ...refSiblings(item), 'x-ref': xref }
             addXRefsAndResolve(obj[i], root, visited)
           } else {
             item['x-ref'] = xref
@@ -150,7 +233,7 @@ function addXRefsAndResolve(obj: any, root: any, visited?: WeakSet<any>) {
           const xref = val.$ref
           const resolved = resolvePointer(root, xref)
           if (resolved !== undefined) {
-            obj[key] = { ...resolved, 'x-ref': xref }
+            obj[key] = { ...resolved, ...refSiblings(val), 'x-ref': xref }
             addXRefsAndResolve(obj[key], root, visited)
           } else {
             val['x-ref'] = xref
@@ -165,22 +248,80 @@ function addXRefsAndResolve(obj: any, root: any, visited?: WeakSet<any>) {
 }
 
 
-// Follow a JSON pointer like "#/components/schemas/Planet"
+// Follow a JSON pointer like "#/components/schemas/Planet".
+//
+// Alias components — `Foo: { $ref: '#/components/schemas/Bar' }` — are a
+// normal OpenAPI idiom, so a pointer can land on another bare $ref node.
+// Follow the chain to its end rather than returning the intermediate: the
+// caller inlines `{ ...resolved }`, and a `$ref` *string* key in that spread
+// is never followed by the object-valued recursion in addXRefsAndResolve, so
+// stopping early yields a schema with no properties and every field is
+// silently dropped. Whether that happened used to depend on whether `paths`
+// or `components` came first in the document, because resolution reads a root
+// the same walk is still mutating.
+//
+// `seen` holds pointer strings (not object identities) so a self- or
+// mutually-referential alias cycle terminates instead of looping forever.
 function resolvePointer(root: any, ref: string): any {
-  if (!ref.startsWith('#/')) return undefined
+  const seen = new Set<string>()
+  // Keywords sitting beside a `$ref` along the chain, outermost first.
+  // OpenAPI 3.1 / JSON Schema 2020-12 allow `$ref` to carry siblings
+  // (`description`, `required`, constraints, ...) and they still apply, so
+  // following the chain must not discard them. Merged onto the final target
+  // below, outermost last so the most specific alias wins.
+  const siblings: any[] = []
+  let current: any = undefined
+  let pointer = ref
+
+  for (; ;) {
+    if (!pointer.startsWith('#/')) return undefined
+    if (seen.has(pointer)) return undefined
+    seen.add(pointer)
+
+    const parts = pointer
+      .substring(2)
+      .split('/')
+      .map(p => p.replace(/~1/g, '/').replace(/~0/g, '~'))
+
+    current = root
+    for (const part of parts) {
+      if (current == null || typeof current !== 'object') return undefined
+      current = current[part]
+    }
 
-  const parts = ref
-    .substring(2)
-    .split('/')
-    .map(p => p.replace(/~1/g, '/').replace(/~0/g, '~'))
+    // Landed on another alias: follow it. Anything else is the target.
+    if (current != null &&
+      'object' === typeof current &&
+      !Array.isArray(current) &&
+      'string' === typeof current.$ref) {
+      const sib: any = {}
+      let hasSib = false
+      for (const k of Object.keys(current)) {
+        if ('$ref' === k) continue
+        sib[k] = current[k]
+        hasSib = true
+      }
+      if (hasSib) siblings.push(sib)
+      pointer = current.$ref
+      continue
+    }
 
-  let current = root
-  for (const part of parts) {
-    if (current == null || typeof current !== 'object') return undefined
-    current = current[part]
-  }
+    if (0 === siblings.length) {
+      // No siblings anywhere on the chain: return the target itself, so
+      // multiple references keep sharing one object (see the note on
+      // addXRefsAndResolve — a fresh copy per site would defeat that).
+      return current
+    }
 
-  return current
+    // Siblings present: a merged view is necessarily a new object. Apply
+    // deepest-first so the outermost alias's keywords win.
+    const merged: any = (null != current && 'object' === typeof current &&
+      !Array.isArray(current)) ? { ...current } : {}
+    for (let i = siblings.length - 1; 0 <= i; i--) {
+      Object.assign(merged, siblings[i])
+    }
+    return merged
+  }
 }
 
 

package/src/transform/field.ts

@@ -4,7 +4,7 @@ import { each, getx } from 'jostraca'
 
 import type { TransformResult, Transform } from '../transform'
 
-import { validator, canonize, inferFieldType, normalizeFieldName } from '../utility'
+import { validator, canonize, inferFieldType, normalizeFieldName, envelopeProp } from '../utility'
 
 import { KIT } from '../types'
 
@@ -150,6 +150,21 @@ function findFieldDefs(
         fieldSets = getx(responses, '201 content "application/json" schema') ??
           getx(responses, '201 schema')
       }
+
+      // Single-entity responses get the same treatment the list branch above
+      // already gives collections: a body that is only an envelope around the
+      // entity — `{item: {...}}` — describes the WRAPPER, not the entity, so
+      // its sole property would otherwise be harvested as a field. That is
+      // how an entity `todoitem` ended up with a required `item` field of
+      // type object, which then appeared in the generated create/update data
+      // types. envelopeProp applies the same two rules used to pick the
+      // response transform, so the field list and the transform agree.
+      if ('list' != mop.name) {
+        const envelope = envelopeProp(fieldSets?.properties, mop.name)
+        if (null != envelope) {
+          fieldSets = fieldSets.properties[envelope]
+        }
+      }
     }
 
     // A QUERY (RFC 10008) request body is a filter/query schema, not the

package/src/transform/top.ts

@@ -44,6 +44,13 @@ const topTransform = async function(
   kit.info = stringifyInfoScalars(def.info ?? {})
   kit.info.servers = stringifyInfoScalars(def.servers ?? [])
 
+  // Guarantee at least one sentence of API description. Many specs (e.g. the
+  // readme.io-hosted Bluefin APIs) ship a placeholder `info.description` of
+  // "." — letterless, useless prose. When the description is empty or has no
+  // letters, synthesise a sentence from the title so the api-info.aontu (and
+  // 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
@@ -120,6 +127,31 @@ 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)
+}
+
+
+// A non-empty, at-least-one-sentence description for the API. Keeps the spec's
+// own `info.description` when it is real prose; otherwise synthesises a sentence
+// from the title (falling back to a generic sentence when even that is
+// missing). Never returns an empty or letterless string.
+function ensureDescription(info: any): string {
+  const current = 'string' === typeof info.description ? info.description.trim() : ''
+  if ('' !== current && hasLetters(current)) {
+    return info.description
+  }
+  const title = 'string' === typeof info.title ? info.title.trim() : ''
+  if ('' === title || !hasLetters(title)) {
+    return 'Client SDK for this API.'
+  }
+  // Avoid a redundant "… Api API." when the title already names itself an API.
+  return 'The ' + title + (/\bapi\b/i.test(title) ? '' : ' API') + '.'
+}
+
+
 // A short one-line description of the API's purpose: the spec's
 // `info.summary` (OpenAPI 3.1) when present, else the first prose sentence
 // of `info.description` with leading markdown headings/blank lines stripped
@@ -129,12 +161,14 @@ function resolveSummary(def: any): string | undefined {
   const info = def?.info ?? {}
 
   const explicit = 'string' === typeof info.summary ? info.summary.trim() : ''
-  if ('' !== explicit) {
+  if ('' !== explicit && hasLetters(explicit)) {
     return firstSentence(explicit)
   }
 
   const desc = 'string' === typeof info.description ? info.description : ''
-  if ('' === desc.trim()) {
+  // Treat letterless prose (a bare "." placeholder, "---", …) as no summary
+  // rather than surfacing it verbatim.
+  if ('' === desc.trim() || !hasLetters(desc)) {
     return undefined
   }
 
@@ -418,6 +452,7 @@ export {
   topTransform,
   resolveSecurity,
   resolveSummary,
+  ensureDescription,
   resolveWebsite,
   homepageFromServer,
   findAuthPrefix,

package/src/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "esModuleInterop": true,
+    "composite": true,
     "module": "nodenext",
     "noEmitOnError": true,
     "outDir":"../dist",

package/src/types.ts

@@ -160,6 +160,11 @@ type Metrics = {
 
 type ApiDefContext = {
   fs: any,
+  // True only when the caller supplied ApiDefOptions.fs (e.g. memfs), as
+  // opposed to the node:fs default. aontu/@tabnas/multisource treats the
+  // presence of an injected fs as "paths are POSIX", so forwarding the real
+  // node:fs breaks include resolution on Windows. See guide/guide.ts.
+  fsInjected: boolean,
   log: any,
   spec: any,
   opts: any,