@voxgig/apidef 8.2.3 → 8.4.0

package/src/guide/heuristic01.ts

@@ -633,6 +633,15 @@ function ResolveEntityName(spec: TaskSpec) {
   ment.entname = entname
   ment.pm = pm
 
+  // Which entity took each path+method, in resolution order. verbOnParent
+  // reads the item path's GET owner from here: a t/p/ item path can be
+  // split across entities by method (a PUT answering with a one-off
+  // acknowledgement is named after it), and the parent of a verb is the
+  // entity a read of the item returns.
+  work.pathowner = work.pathowner ?? {}
+  work.pathowner[pathStr] = work.pathowner[pathStr] ?? {}
+  work.pathowner[pathStr][methodName] = entname
+
   debugpath(pathStr, methodName, 'RESOLVE-ENTITY-NAME',
     formatJSONIC({ entdesc, ment }, { hsepd: 0, $: true, color: true }))
 }
@@ -737,6 +746,10 @@ function RenameParams(spec: TaskSpec) {
         oldParam.endsWith('id')
         || oldParam.endsWith('Id')
         || canonize(oldParam) === parentName
+        // GitHub-style `<parent>_number` keys (pull_number, issue_number):
+        // the parent's own key under another name. Only when the param sits
+        // under its own entity, so a nested collection keeps its parent key.
+        || (oldParam.endsWith('_number') && parentName === entdesc.name)
 
       debugpath(pathStr, mdesc.method, 'RENAME-PARAM-PART', parts, partI, partStr, {
         lastPart,
@@ -960,8 +973,20 @@ function FindActions(spec: TaskSpec) {
 
   const cmp = ment.cmp
 
+  // A verb that ResolveEntityName assigned to its parent entity
+  // (verbOnParent) is an action whatever the parent literal canonizes to:
+  // `/app/installations/{installation_id}/access_tokens` belongs to `app`.
+  // Recorded directly rather than through updateAction, whose guard against
+  // an entity "already encoding" the verb would drop `archive` on
+  // `email_archive` and leave the verb as a plain CRUD point.
+  if (null != ment.verb_on_parent) {
+    pathdesc.action[lastPartCanon] = pathdesc.action[lastPartCanon] ?? {
+      why_action: ['ent', entdesc.name, 'verb-on-parent', lastPart, methodName],
+    }
+  }
+
   // /api/foo/bar where foo is the entity and bar is the action, no id param
-  if (
+  else if (
     secondLastPartCanon === cmp
     || secondLastPartCanon === ment.origcmp
     || secondLastPartCanon === entname
@@ -1272,9 +1297,17 @@ function entityPathMatch_tpte(
   let ecm = undefined
 
   if (null != ment.cmp) {
-    ecm = entityCmpMatch(data, entname, mdesc, why)
-    entname = ecm.name
-    why.push('has-cmp=' + ecm.orig)
+    const parent = verbOnParent(data, pm, mdesc)
+    if (null != parent) {
+      entname = parent
+      ment.verb_on_parent = getelem(pm, -1)
+      why.push('verb-on-parent=' + parent)
+    }
+    else {
+      ecm = entityCmpMatch(data, entname, mdesc, why)
+      entname = ecm.name
+      why.push('has-cmp=' + ecm.orig)
+    }
   }
 
   else if (probableEntityMethod(data, mdesc, pm, why)) {
@@ -1312,6 +1345,103 @@ function endsWithCmp(data: any, pm: PathMatch) {
 }
 
 
+// A write on `.../<parent>/{id}/<verb>` is a VERB ON THE PARENT, not an
+// entity named after its result shape.
+//
+// GitHub's `PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge` answers with
+// a `pull-request-merge-result` component. Naming the method's entity after
+// that component (the cmp-primary rule) produced a `pull_request_merge_result`
+// entity with a single `update` op, while the GET on the same path (no
+// response schema) stayed an action on `pull`: one route split across two
+// entities by method, and the verb unreachable from the entity it acts on.
+//
+// Five signals, together: the method writes (a GET on such a path is a
+// sub-resource read and keeps the component rule); the response component
+// occurs nowhere else in the spec (a one-off result, not a resource shape);
+// that component is not the literal's own collection shape (a create-only
+// `POST .../{id}/labels` answering with a `label` is a nested collection,
+// not a verb); the item selector itself (`.../pulls/{pull_number}`) is a
+// path of the spec, so the trailing literal cannot be a collection of its
+// own; and nothing extends the path (`.../private-registries/{secret_name}`
+// makes `private-registries` a collection, whatever its POST answers with).
+// The verb then joins the parent entity, where FindActions records it as an
+// action and select stamps `$action` on its points. Returns the parent's
+// entity name, or null when the rule does not apply.
+function verbOnParent(
+  data: { def: any, guide: any, work: any },
+  pm: PathMatch,
+  mdesc: any,
+): null | string {
+  const method = mdesc.method
+  if ('GET' === method || 'QUERY' === method || 'HEAD' === method || 'OPTIONS' === method) {
+    return null
+  }
+
+  const ment = mdesc.MethodEntity
+  if (1 < (ment.cmpoccur ?? 0)) {
+    return null
+  }
+
+  // A PLURAL literal names a nested collection, whatever it answers with:
+  // `asset_keys` under `{environment_id}` creates an asset key, and
+  // `approvals` under `{merge_request_iid}` is a collection of approvals.
+  // A verb is singular — `merge`, `revoke`, `resend_confirmation` — so the
+  // component rule below is never reached for a plural, which is what keeps
+  // a create-only collection an entity of its own.
+  const lit = snakify(getelem(pm, -1))
+  if ('' === lit || depluralize(lit) !== lit) {
+    return null
+  }
+
+  // A singular literal still names a collection when its response component
+  // is that collection's member shape (`label` answering with `label`, or
+  // with a parent-prefixed `thing_label`); a verb answers with something
+  // else.
+  const verb = canonize(getelem(pm, -1))
+  const cmp = String(ment.cmp ?? '')
+  if ('' === verb || cmp === verb || cmp.endsWith('_' + verb)) {
+    return null
+  }
+
+  const defpaths = data.def?.paths ?? {}
+
+  // Paths compare with parameters normalised: the item path may spell its
+  // key `{id}` where the verb path spells it `{thing_number}`.
+  const normalize = (p: string) => p.replace(/\{[^}]+\}/g, '{}')
+  const itemNorm = normalize(pm.path.replace(/\/[^/]+$/, ''))
+  const prefix = normalize(pm.path) + '/'
+
+  let itemPath: undefined | string = undefined
+  for (const p of Object.keys(defpaths)) {
+    const pn = normalize(p)
+    if (pn === itemNorm) {
+      itemPath = p
+    }
+    // A leaf: no path continues past the verb. Compared on a segment
+    // boundary, so `/merge` is not "extended" by `/merge-async`.
+    else if (pn.startsWith(prefix)) {
+      return null
+    }
+  }
+  if (null == itemPath) {
+    return null
+  }
+
+  // Methods resolve in path order, so the item path's owners are already
+  // known. The parent is the entity a READ of the item returns: a PUT on
+  // the item answering with a one-off acknowledgement is named after that
+  // and must not claim the verb. Fall back to any owner, then the literal.
+  const owners = data.work.pathowner?.[itemPath] ?? {}
+  const parent = owners.GET ?? owners.QUERY ??
+    Object.values(owners).sort()[0] as undefined | string
+  if (null != parent) {
+    return parent
+  }
+
+  return canonize(getelem(pm, -3))
+}
+
+
 function isOrigCmp(data: any, name: string) {
   return null != data.guide.metrics.count.origcmprefs[name]
 }

package/src/model.ts

@@ -84,6 +84,23 @@ type ModelField = {
   // `description`. Absent when the spec does not describe the property —
   // generators render an empty cell rather than inventing prose.
   short?: string
+
+  // SPEC FACTS ABOUT THE FIELD ITSELF, carried through verbatim from the
+  // OpenAPI property. Facts the spec states, not inferences.
+  //
+  // `readOnly` is the load-bearing one: it is the difference between a field
+  // a client MAY send and one it may not, which nothing else in this record
+  // expresses. Without it every generator necessarily puts server-assigned
+  // fields into the type a caller fills in.
+  //
+  // The booleans are present ONLY when the spec declares them true — each
+  // defaults to false in OpenAPI, so absent and explicit-false mean the same
+  // thing and emitting the false ones would change every model for no
+  // information. `format` is present only for a non-empty string.
+  readOnly?: boolean
+  writeOnly?: boolean
+  deprecated?: boolean
+  format?: string
   union?: {
     count: number     // how many untagged unions lie beneath the field
     branches: number  // widest branch count among them
@@ -215,6 +232,16 @@ type ModelEntity = {
   id?: {
     name: string
     field: string
+    // COMPOSITE IDENTITY. Present only when the API addresses one record by
+    // MORE THAN ONE path parameter, so no single parameter is the id.
+    // github's repo is the case: GET /repos/{owner}/{repo} needs both, and
+    // neither alone names a repository.
+    //
+    // `parts` are those parameters in path order; `sep` joins them into the
+    // one `id` an SDK entity carries. Absent means the ordinary single-key
+    // entity, so downstream can branch on presence alone.
+    parts?: string[]
+    sep?: string
   }
   relations: ModelEntityRelations
 }

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],
     }