@voxgig/apidef 8.2.3 → 8.3.0

package/src/transform/args.ts

@@ -71,7 +71,7 @@ const argsTransform: Transform = async function(
           argdefs.push(...(opdef?.parameters ?? []))
         }
 
-        resolveArgs(ment, mop, mpoint, argdefs)
+        resolveArgs(ctx, ment, mop, mpoint, argdefs)
       })
 
     })
@@ -116,7 +116,10 @@ const ARG_KIND: Record<string, ModelArg["kind"]> = {
 }
 
 
-function resolveArgs(ment: ModelEntity, mop: ModelOp, mpoint: ModelPoint, argdefs: ParameterDef[]) {
+function resolveArgs(
+  ctx: any,
+  ment: ModelEntity, mop: ModelOp, mpoint: ModelPoint, argdefs: ParameterDef[]
+) {
   const touchedKeys = new Set<string>()
 
   each(argdefs, (argdef: ParameterDef) => {
@@ -124,6 +127,27 @@ function resolveArgs(ment: ModelEntity, mop: ModelOp, mpoint: ModelPoint, argdef
     // by; the snakified form is the user-friendly runtime identifier.
     const specName = normalizeFieldName(argdef.name)
     const orig = depluralize(snakify(specName))
+
+    // A parameter with no name is not a parameter. This is what a DANGLING
+    // `$ref` looks like by the time it reaches here: the reference survives
+    // unresolved, `name` and `in` are both absent, and the arg would become
+    // a nameless `query` entry that every target then has to render. Ruby
+    // cannot: `Struct.new(:"")` raises at load and takes the whole SDK with
+    // it. Drop it and say which reference is missing.
+    if ('' === orig) {
+      const ref = (argdef as any)?.$ref
+      ctx?.warn?.({
+        note: `Parameter with no name on entity=${ment.name} op=${mop.name}` +
+          ` path=${mpoint.orig} is dropped` +
+          (null == ref ? '.' : `: \`$ref\` "${ref}" resolves to nothing.`) +
+          ' A parameter needs a `name`, or a reference that resolves to one.',
+        entity: ment.name,
+        path: mpoint.orig,
+        op: mop.name,
+      })
+      return
+    }
+
     const kind = ARG_KIND[argdef.in] ?? 'query'
     // Rename map can be keyed by either the spec original (camelCase) or by
     // the snakified form depending on which path went through heuristic01.

package/src/transform/entity.ts

@@ -241,6 +241,7 @@ function resolvePathList(guideEntity: GuideEntity, def: { paths: Record<string,
       rename,
       method: '', // operation collectOps will copy and assign per op
       op: guidePath.op,
+      action: guidePath.action,
       def: def.paths[orig],
     }
 

package/src/transform/field.ts

@@ -182,6 +182,34 @@ function resolveOpFields(
       }
     }
 
+    // SPEC FACTS ABOUT THE FIELD, carried through verbatim.
+    //
+    // These four are declared by OpenAPI on the property and were being
+    // dropped on the floor. `readOnly` is the one that matters most: it is
+    // the difference between a field a client MAY send and one it may not,
+    // and nothing else in the model says which — so every generator has been
+    // putting server-assigned fields into the type a caller fills in.
+    //
+    // ONLY WHEN THE SPEC SAYS SO, and for the booleans only when TRUE. Each
+    // defaults to false in OpenAPI, so an absent key and an explicit `false`
+    // carry the same information; emitting the false ones would add a key to
+    // every field of every model and say nothing. Same discipline as
+    // `short`: absent means "the spec did not say", never "apidef dropped
+    // it".
+    for (const flag of ['readOnly', 'writeOnly', 'deprecated'] as const) {
+      if (true === (fielddef as any)[flag]) {
+        mfield[flag] = true
+      }
+    }
+
+    // `format` is an open vocabulary — OpenAPI defines a handful and lets a
+    // spec coin its own — so it is carried as the string it is rather than
+    // interpreted here. `password` is the one a generator acts on today.
+    const ffmt = (fielddef as any).format
+    if ('string' === typeof ffmt && '' !== ffmt.trim()) {
+      mfield.format = ffmt.trim()
+    }
+
     // Record an untagged union under this field. The field is already typed
     // openly ($ANY/$ARRAY/$OBJECT) because there is nothing to narrow it to;
     // this says WHY, so the generated docs can explain the open type instead
@@ -536,6 +564,23 @@ function mergeField(
     existingField.short = newField.short
   }
 
+  // The spec facts merge the same way, and for the same reason: one schema
+  // annotates the field and another references it bare, so taking the first
+  // declaration in opFieldPrecedence order is what finds the annotation.
+  //
+  // THE PRECEDENCE ORDER PUTS `load` FIRST, WHICH IS THE SAFE DIRECTION HERE.
+  // A field the response schema marks readOnly and a request body also lists
+  // is a self-contradictory spec — OpenAPI says a client must not send a
+  // readOnly property at all — and this resolves it by believing the
+  // restriction rather than the omission. Marking a writable field readOnly
+  // costs a caller one field; the other way round sends a value the server
+  // rejects.
+  for (const flag of ['readOnly', 'writeOnly', 'deprecated', 'format'] as const) {
+    if (null == existingField[flag] && null != newField[flag]) {
+      (existingField as any)[flag] = newField[flag]
+    }
+  }
+
   return existingField
 }
 

package/src/transform/operation.ts

@@ -25,6 +25,18 @@ import type {
 
 
 
+// The op names the transform resolves. Anything else under a guide path's
+// `op` map is dropped, and an unknown name (a verb such as `merge`, or a
+// typo) is dropped WITH A WARNING: guide.aon is the only correction surface
+// (ADR-002), so a correction that vanishes silently defeats it. A non-CRUD
+// verb is declared as `action: <verb>: {}` beside a CRUD op on the same path.
+const RESOLVED_OPS = ['load', 'list', 'create', 'update', 'remove', 'patch']
+
+// Emitted by the heuristic for HEAD and OPTIONS methods; no SDK operation
+// exists for them yet, so they are skipped without a warning.
+const IGNORED_OPS = ['head', 'options', 'OPTIONS']
+
+
 const operationTransform: Transform = async function(
   ctx: any,
 ): Promise<TransformResult> {
@@ -36,7 +48,7 @@ const operationTransform: Transform = async function(
   each(guide.entity, (gent: GuideEntity, entname: string) => {
     if (!guideActive(gent)) return
 
-    collectOps(gent)
+    collectOps(ctx, gent)
 
     const opm: ModelOpMap = {
       load: undefined,
@@ -63,7 +75,7 @@ const operationTransform: Transform = async function(
 }
 
 
-function collectOps(gent: GuideEntity) {
+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) => {
@@ -72,6 +84,20 @@ function collectOps(gent: GuideEntity) {
         return
       }
 
+      if (!RESOLVED_OPS.includes(opname)) {
+        if (!IGNORED_OPS.includes(opname)) {
+          ctx.warn?.({
+            note: `Unknown op "${opname}" on entity=${gent.name} path=${pathdesc.orig}` +
+              ` is dropped: only ${RESOLVED_OPS.join('/')} are resolved.` +
+              ` Declare a verb as \`action: ${opname}: {}\` beside a CRUD op on that path.`,
+            entity: gent.name,
+            path: pathdesc.orig,
+            op: opname,
+          })
+        }
+        return
+      }
+
       ; (gent as any).opm$[opname] = (gent as any).opm$[opname] ?? { paths: [] }
 
       const oppathdesc: PathDesc = {
@@ -80,6 +106,7 @@ function collectOps(gent: GuideEntity) {
         rename: pathdesc.rename,
         method: gop.method as any,
         op: gop as any,
+        action: pathdesc.action,
         def: pathdesc.def,
       }
 
@@ -126,7 +153,18 @@ function resolvePatch(opm: ModelOpMap, gent: GuideEntity): undefined | ModelOp {
   const opdesc = resolveOp('patch', gent)
 
   // If patch is actually update, make it update!
-  if (null != opdesc && null == opm.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)
+    }
     opm.update = opdesc
     opm.update.name = 'update'
   }
@@ -138,6 +176,14 @@ function resolvePatch(opm: ModelOpMap, gent: GuideEntity): undefined | ModelOp {
 }
 
 
+// True when every path collected under the op carries a guide action.
+function onlyActionPaths(gent: GuideEntity, opname: OpName): boolean {
+  const paths: PathDesc[] = (gent as any).opm$?.[opname]?.paths ?? []
+  return 0 < paths.length &&
+    paths.every((p: PathDesc) => 0 < Object.keys(p.action ?? {}).length)
+}
+
+
 function resolveOp(opname: OpName, gent: GuideEntity): undefined | ModelOp {
   let mop: undefined | ModelOp = undefined
   let opdesc = (gent as any).opm$[opname]

package/src/utility.ts

@@ -1070,6 +1070,37 @@ function canonizeCmpName(orig: string): string {
 }
 
 
+const FIRST_LETTER_RE = /[a-zA-Z]/
+
+
+// No target language permits an identifier that starts with a digit, so a
+// name derived from one — a `3dsSession` schema, a `/2fa` path segment, a
+// `_3DSecure` GraphQL type — is prefixed with an `n`.
+//
+// The prefix takes the case of the name it guards: lower for `3ds_session`,
+// upper for `3DSecure`. That keeps the result inside whatever casing
+// convention the caller was already working in, so a later PascalCase or
+// camelCase conversion has nothing to undo. A name with no letter in it at
+// all (`404`) takes the lower-case prefix.
+//
+// This is the ONE place the rule lives. Entity names reach it through
+// `ensureMinEntityName` and the GraphQL guide's `entityName`; project slugs
+// through `sanitizeSlug`.
+//
+// FIELD names deliberately do NOT come here. A field name is a WIRE
+// identifier and renaming it makes the SDK read a key the server never sends
+// — the mistake `canonizeField` exists to document. Targets escape those at
+// the point of emission instead.
+function prefixLeadingDigit(s: string): string {
+  if (null == s || '' === s) return s
+  const first = s.charCodeAt(0)
+  if (first < 48 || first > 57) return s
+  const letter = s.match(FIRST_LETTER_RE)
+  const upper = null != letter && letter[0] >= 'A' && letter[0] <= 'Z'
+  return (upper ? 'N' : 'n') + s
+}
+
+
 // Sanitize a raw slug into a clean kebab-case string suitable for
 // conversion to a valid JS identifier (via camelify/snakify/etc).
 function sanitizeSlug(s: string): string {
@@ -1098,12 +1129,7 @@ function sanitizeSlug(s: string): string {
 
   if (!out) return 'unknown'
 
-  // Ensure the slug does not start with a digit (invalid for JS identifiers)
-  if (/^\d/.test(out)) {
-    out = 'n' + out
-  }
-
-  return out
+  return prefixLeadingDigit(out)
 }
 
 
@@ -1172,9 +1198,7 @@ function ensureMinEntityName(
     padded = truncated || parts[0].substring(0, MAX_ENTITY_NAME_LEN)
   }
 
-  if (padded.length > 0 && padded[0] >= '0' && padded[0] <= '9') {
-    padded = 'n' + padded
-  }
+  padded = prefixLeadingDigit(padded)
   if (padded.length < MIN_ENTITY_NAME_LEN) {
     const padding = 'nt'.substring(0, MIN_ENTITY_NAME_LEN - padded.length)
     padded = padded + padding
@@ -1956,6 +1980,7 @@ export {
   ensureMinEntityName,
   inferFieldType,
   normalizeFieldName,
+  prefixLeadingDigit,
   debugpath,
   findPathsWithPrefix,
   writeFileSyncWarn,