@voxgig/apidef 6.3.7 → 6.3.9

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,

package/src/utility.ts

@@ -6,7 +6,7 @@ import { snakify, camelify, kebabify, each } from 'jostraca'
 import { decircular } from '@voxgig/util'
 
 import {
-  slice, merge, inject, clone, isnode, walk, transform, select,
+  slice, merge, inject, clone, isnode, walk, transform, select, keysof,
   Injection,
   M_VAL,
   M_KEYPRE,
@@ -134,7 +134,12 @@ function formatJsonSrc(jsonsrc: string) {
 //
 // Keys are lowercase; depluralize() does a case-insensitive lookup
 // and reapplies the caller's casing on the way out.
-const IRREGULARS: Record<string, string> = {
+//
+// Null-prototype: these tables are indexed by spec-derived names, so a
+// schema or path segment called `constructor` / `__proto__` / `toString`
+// would otherwise resolve to the inherited Object member and be returned
+// as a "match" — crashing matchCase() on a function. See NULL_PROTO_NOTE.
+const IRREGULARS: Record<string, string> = Object.assign(Object.create(null), {
   'analytics': 'analytics',
   'analyses': 'analysis',
   'appendices': 'appendix',
@@ -198,7 +203,18 @@ const IRREGULARS: Record<string, string> = {
   'vertices': 'vertex',
   'women': 'woman',
   'yes': 'yes',
-}
+})
+
+// NULL_PROTO_NOTE: every plain-object lookup table in this module whose keys
+// come from an API spec is built with a null prototype
+// (`Object.assign(Object.create(null), {...})`). Without it, `TABLE[name]`
+// inherits from Object.prototype, so `TABLE['constructor']` yields the Object
+// constructor (truthy, a function) and `TABLE['__proto__']` yields
+// Object.prototype (truthy, an object). Both then flow into code expecting a
+// string. A spec with `components.schemas.Constructor` is enough to reach
+// this: canonize -> depluralize -> matchCase -> `.toLowerCase is not a
+// function`, failing the whole build at the guide stage. Keep new tables
+// null-prototype, or use a Map (CANONIZE_CACHE already does).
 
 // Sorted longest-first so the most specific IRREGULARS suffix wins.
 // Without this, 'women' would be shadowed by 'men' (3 < 5) under
@@ -235,12 +251,13 @@ function matchCase(source: string, target: string): string {
 // inherit the override without signature churn. apidef is
 // single-model-per-process; if that ever changes, switch this to a
 // per-context map.
-let CUSTOM_PLURALS: Record<string, string> = {}
+// Null-prototype: see NULL_PROTO_NOTE above.
+let CUSTOM_PLURALS: Record<string, string> = Object.create(null)
 let CUSTOM_PLURAL_KEYS: string[] = []
 
 
 function setCustomPlurals(plurals: Record<string, string> | undefined | null) {
-  CUSTOM_PLURALS = {}
+  CUSTOM_PLURALS = Object.create(null)
   if (plurals) {
     for (const k of Object.keys(plurals)) {
       // Skip null/undefined values so a partially-typed model entry
@@ -752,7 +769,7 @@ function formatJSONIC(
   }
 
   return renderJSONIC(val, hsepd, showd, useColor, maxlines, exclude, c,
-    renderPrimitive, renderComment)
+    renderPrimitive, renderComment, false)
 }
 
 
@@ -766,6 +783,12 @@ function renderJSONIC(
   c: (color: any, text: string) => string,
   renderPrimitive: (v: any) => string,
   renderComment: (c: any) => string | null,
+  // True once the value has already been through decircular. `seen` never
+  // forgets a node, so a merely REPEATED reference (a shared node in a DAG,
+  // not a cycle) also lands in the fallback below. If decircular leaves such
+  // a repeat in place, retrying forever overflows the stack — which is what
+  // formatting a deep validation error used to do. Retry at most once.
+  decircularized: boolean,
 ): string {
 
   const space = '  '
@@ -782,6 +805,10 @@ function renderJSONIC(
     kind: 'close'
     token: '}' | ']'
     indentLevel: number
+    // The container this frame closes. `seen` tracks the ANCESTOR PATH, so
+    // the node is removed again on the way out — otherwise a merely repeated
+    // (shared) node is indistinguishable from a cycle.
+    node?: any
   }
 
   const seen = new WeakSet()
@@ -807,6 +834,9 @@ function renderJSONIC(
     top -= 1
 
     if (frame.kind === 'close') {
+      if (undefined !== frame.node) {
+        seen.delete(frame.node)
+      }
       const indent = space.repeat(frame.indentLevel)
       const hsep = 0 < frame.indentLevel && frame.indentLevel <= hsepd
       lines.push(`${indent}${c('bracket', frame.token)}${hsep ? '\n' : ''}`)
@@ -826,10 +856,29 @@ function renderJSONIC(
       continue
     }
 
-    // Circular reference detected — fall back to decircular
+    // Repeated reference — fall back to decircular, but only once.
     if (seen.has(v)) {
-      return renderJSONIC(decircular(val), hsepd, showd, useColor, maxlines, exclude, c,
-        renderPrimitive, renderComment)
+      if (!decircularized) {
+        // decircular recurses per level, so a deep value can overflow the
+        // stack inside it. This whole path usually runs while formatting an
+        // error, so degrade to the marker instead of throwing over it.
+        let flat: any
+        try {
+          flat = decircular(val)
+        }
+        catch (err: any) {
+          flat = undefined
+        }
+        if (undefined !== flat) {
+          return renderJSONIC(flat, hsepd, showd, useColor, maxlines, exclude, c,
+            renderPrimitive, renderComment, true)
+        }
+      }
+      // decircular did not resolve it, so render a marker rather than
+      // recursing again. Better a placeholder than a crash while
+      // formatting an error the user actually needs to read.
+      lines.push(`${linePrefix}${c('string', '"[Circular]"')}${commentSuffix}`)
+      continue
     }
     seen.add(v)
 
@@ -837,13 +886,13 @@ function renderJSONIC(
       const arr = v as any[]
       if (arr.length === 0) {
         lines.push(`${linePrefix}${c('bracket', '[')}${commentSuffix}`)
-        stack[++top] = { kind: 'close', token: ']', indentLevel }
+        stack[++top] = { kind: 'close', token: ']', indentLevel, node: v }
         continue
       }
 
       // opening line
       lines.push(`${linePrefix}${c('bracket', '[')}${commentSuffix}`)
-      stack[++top] = { kind: 'close', token: ']', indentLevel }
+      stack[++top] = { kind: 'close', token: ']', indentLevel, node: v }
 
       // children (reverse push)
       const childPrefix = space.repeat(indentLevel + 1)
@@ -872,13 +921,13 @@ function renderJSONIC(
 
     if (printableKeys.length === 0) {
       lines.push(`${linePrefix}${c('bracket', '{')}${commentSuffix}`)
-      stack[++top] = { kind: 'close', token: '}', indentLevel }
+      stack[++top] = { kind: 'close', token: '}', indentLevel, node: v }
       continue
     }
 
     // opening line
     lines.push(`${linePrefix}${c('bracket', '{')}${commentSuffix}`)
-    stack[++top] = { kind: 'close', token: '}', indentLevel }
+    stack[++top] = { kind: 'close', token: '}', indentLevel, node: v }
 
     const nextIndentStr = space.repeat(indentLevel + 1)
     for (let i = printableKeys.length - 1; i >= 0; i--) {
@@ -905,7 +954,17 @@ function renderJSONIC(
 }
 
 
-const VALID_CANON: Record<string, string> = {
+// Canonical type-sentinel vocabulary. VALID_CANON maps an OpenAPI type NAME
+// to its `$SENTINEL` form; CANON_ONE is the union sentinel produced by
+// `validator` for a multi-type (`['`$ONE`', [member, ...]]`). Both are part
+// of the public API so downstream consumers (e.g. @voxgig/sdkgen's
+// sentinel -> language-type table) can verify they cover the full set
+// instead of hand-syncing against this file.
+//
+// Null-prototype (see NULL_PROTO_NOTE): `type` values come from the spec, so
+// a schema declaring `type: constructor` would otherwise return the Object
+// constructor here rather than falling through to the 'Any' default.
+const VALID_CANON: Record<string, string> = Object.assign(Object.create(null), {
   'string': '`$STRING`',
   'number': '`$NUMBER`',
   'integer': '`$INTEGER`',
@@ -914,7 +973,9 @@ const VALID_CANON: Record<string, string> = {
   'array': '`$ARRAY`',
   'object': '`$OBJECT`',
   'any': '`$ANY`',
-}
+})
+
+const CANON_ONE = '`$ONE`'
 
 
 function validator(torig: undefined | string | string[]): any {
@@ -924,7 +985,7 @@ function validator(torig: undefined | string | string[]): any {
     return canon
   }
   else if (Array.isArray(torig)) {
-    return ['`$ONE`', torig.map((t: string) => validator(t))]
+    return [CANON_ONE, torig.map((t: string) => validator(t))]
   }
   else {
     return '`$ANY`'
@@ -1376,6 +1437,150 @@ export type {
   PathMatch
 }
 
+
+// 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
+}
+
+
+// A response body that is nothing but a single wrapper property is an
+// ENVELOPE around the result: `{item: {...}}`, `{data: {...}}`,
+// `{items: [...]}`, `{results: [...]}`. Return that property's name so the
+// caller can unwrap to it, or null when the body is the result itself.
+//
+// Two conditions keep this from firing on a response that IS the entity:
+//
+//   1. EXACTLY ONE property. A body with siblings is a structure in its own
+//      right, not a wrapper — `{ok, id}` from a delete, or any paged
+//      `{results, next}`, must be handed over whole.
+//   2. The property's SHAPE matches the operation's cardinality. A `list`
+//      unwraps only to an array, every other op only to a non-array. So a
+//      single-entity op facing `{items: [...]}` is left alone rather than
+//      silently yielding a list, and vice versa.
+//
+// A one-field entity whose sole field is itself structured can still be
+// unwrapped wrongly; that is the residual cost of the spec not saying which
+// it means. Naming the wrapper after the entity remains the unambiguous
+// signal, and is still checked first.
+function envelopeProp(resprops: any, opname: string): string | null {
+  const keys = keysof(resprops)
+  if (1 !== keys.length) {
+    return null
+  }
+
+  const key = keys[0]
+  const prop = resprops[key]
+  if (!isEntityWrapperProp(prop)) {
+    return null
+  }
+
+  const islist = propIsList(prop)
+  if (null == islist || islist !== ('list' === opname)) {
+    return null
+  }
+
+  return key
+}
+
+
+// Is this schema a collection? null when the schema does not say.
+//
+// `isEntityWrapperProp` accepts a composed schema (allOf/oneOf/anyOf) as
+// structured, but a composed schema carries no outer `type` or `items` — so
+// reading those alone silently called it a non-list. A `list` then kept its
+// envelope, and worse, a single-entity op unwrapped to an array-valued
+// property. Composed branches are inspected instead, and unanimity required:
+// a union that is an array in one branch and an object in another does not
+// say what the caller will get, and an envelope is not worth guessing at.
+function propIsList(schema: any): boolean | null {
+  if (null == schema || 'object' !== typeof schema) {
+    return null
+  }
+
+  const branches = schema.allOf ?? schema.oneOf ?? schema.anyOf
+  if (Array.isArray(branches)) {
+    if (0 === branches.length) {
+      return null
+    }
+    const first = propIsList(branches[0])
+    if (null == first) {
+      return null
+    }
+    for (const branch of branches) {
+      if (propIsList(branch) !== first) {
+        return null
+      }
+    }
+    return first
+  }
+
+  return 'array' === schema.type || null != schema.items
+}
+
+
+// The request BODY a closed schema permits, as a transform mapping.
+//
+// `additionalProperties: false` is the spec saying the server rejects any
+// property it did not declare. When a body says that, sending the caller's
+// whole request payload is wrong: an op's payload also carries its PATH
+// params (`id` for `PUT /item/{id}`), and a closed shape 400s the entire
+// request over that one extra key. Restricting the body to the declared
+// properties is then not a heuristic — it is what the spec asked for.
+//
+// Returns null for an open or property-less schema, where `reqdata` (send
+// everything) remains the right default: an open body accepts extras, and
+// with no declared properties there is nothing to restrict to.
+//
+// The KEY is the property's wire name — that is what goes on the wire and
+// what the server matches against. The SOURCE is read by the field's
+// CANONICAL name, because that is the only name the caller ever sees:
+// findFieldDefs runs every property through `canonize(normalizeFieldName())`,
+// so a spec property `UserName` reaches the generated request type as
+// `user_name`. Reading `reqdata.UserName` would find nothing and send
+// undefined.
+function closedBodyTransform(schema: any): Record<string, string> | null {
+  if (null == schema || 'object' !== typeof schema) {
+    return null
+  }
+  if (false !== schema.additionalProperties) {
+    return null
+  }
+
+  const names = keysof(schema.properties)
+  if (0 === names.length) {
+    return null
+  }
+
+  // Null prototype: a spec is free to declare a property called `__proto__`,
+  // and on an ordinary object that assignment sets the prototype instead of
+  // creating an own property — the mapping would vanish, and with it the
+  // whole body restriction if it were the only one.
+  const out: Record<string, string> = Object.create(null)
+  for (const name of names) {
+    out[name] = '`reqdata.' + canonize(normalizeFieldName(name)) + '`'
+  }
+  return out
+}
+
 export {
   nom,
   getdlog,
@@ -1390,6 +1595,8 @@ export {
   makeWarner,
   formatJSONIC,
   validator,
+  VALID_CANON,
+  CANON_ONE,
   canonize,
   canonizeCmpName,
   stripSchemaNamespace,
@@ -1408,5 +1615,8 @@ export {
   getModelPath,
   sortedKeys,
   sortedEntries,
+  isEntityWrapperProp,
+  envelopeProp,
+  closedBodyTransform,
 
 }