@voxgig/apidef 8.3.0 → 8.5.0

package/src/transform/field.ts

@@ -32,7 +32,7 @@ import type {
 const fieldTransform: Transform = async function(
   ctx: any,
 ): Promise<TransformResult> {
-  const { apimodel, def } = ctx
+  const { apimodel, def, guide, model } = ctx
   const kit: KitModel = apimodel.main[KIT]
 
   let msg = 'field '
@@ -72,9 +72,101 @@ const fieldTransform: Transform = async function(
     // Downstream (test generators, fixture builders) gate id-specific code on
     // this presence so that public read-only APIs without ids don't get
     // bogus id assertions.
+    // COMPOSITE FIRST, because a compound key need not come with an `id`.
+    //
+    // An entity addressed by `{owner}/{repo}` whose response carries only
+    // `owner` and `name` has no field literally named `id`, and its adjacent
+    // placeholders are left unrenamed so `addressedById` is false too.
+    // Neither branch below then ran, so the entity got NO id descriptor and
+    // even an explicit `guide.entity.<name>.id.parts` was silently ignored —
+    // while the Go port, which initialises a descriptor unconditionally,
+    // emitted the composite. The ports disagreed on exactly the shape this
+    // feature exists for.
+    const gent = guide?.entity?.[ment.name]
+    const composite = compositeId(ment, gent, def)
+
     const idField = fields.find((f: ModelField) => 'id' === f.name)
-    if (idField) {
-      ment.id = { name: 'id', field: 'id' }
+
+    // A COMPOSITE ID IS A STRING, whatever the API's own `id` field is —
+    // AND THE API'S OWN id IS KEPT.
+    //
+    // github's repo declares `id` as an integer, its global database id,
+    // while the composite identity is `owner/repo`. Two facts have to
+    // survive: `id` must hold a string, because that is what the joined
+    // value is and what every generated type has to store; and the spec's
+    // numeric property must not be silently reinterpreted, because a
+    // consumer that wants the database id is entitled to it with its own
+    // type and format intact.
+    //
+    // So the API's field MOVES to `<api>_id` rather than being rewritten in
+    // place, carrying its type, format and per-op overrides with it, and the
+    // entity's `alias.field` map records where it went. Retyping in place
+    // (the first attempt) claimed the server's numeric id was a string;
+    // leaving it alone made `id.field` name a declaration the runtime value
+    // cannot satisfy. Moving it is the only option that lies about neither.
+    if (null != composite.parts && null != idField && !scalarStringField(idField)) {
+      const idf: any = idField
+      const apiname = String((model as any)?.name || 'api')
+      const keep = apiname + '_id'
+
+      if (!fields.some((f: ModelField) => f.name === keep)) {
+        // A DEEP COPY, because the move is followed by deletions on the
+        // original. A spread shares the `op` object, so clearing the stale
+        // per-op `type` off `id` cleared it off the preserved field too —
+        // the preservation preserved nothing for exactly the key it was
+        // added to keep.
+        fields.push(JSON.parse(JSON.stringify({ ...idf, name: keep })) as any)
+
+        const alias = ((ment as any).alias = (ment as any).alias || {})
+        alias.field = alias.field || {}
+        alias.field[keep] = 'id'
+      }
+
+      idf.type = '`$STRING`'
+      // The facts that described the moved type go with it: `format: int64`
+      // beside a string, or a per-op `type` override still saying integer,
+      // is a model contradicting itself — and the op override is what a
+      // generator reads for that op.
+      delete idf.format
+      for (const opname of Object.keys(idf.op || {})) {
+        delete idf.op[opname].type
+      }
+
+      fields.sort((a: ModelField, b: ModelField) =>
+        a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+    }
+
+    if (null != composite.parts && null == idField) {
+      // The FIELD as well as the descriptor, for the reason the branch below
+      // documents: a model that declares the descriptor without the field
+      // makes the generated type disagree with the generated test.
+      fields.push({
+        name: 'id',
+        type: '`$STRING`',
+        req: false,
+      } as any)
+      fields.sort((a: ModelField, b: ModelField) =>
+        a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+    }
+
+    const singleKey = (composite as any).single
+    delete (composite as any).single
+
+    if (null == idField && null != singleKey && null == composite.parts) {
+      // The guide disabled composite; the terminal parameter is the key, and
+      // the entity needs the field to carry it for the same reason the
+      // composite branch above does.
+      fields.push({
+        name: 'id',
+        type: '`$STRING`',
+        req: false,
+      } as any)
+      fields.sort((a: ModelField, b: ModelField) =>
+        a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+    }
+
+    if (idField || null != composite.parts || null != singleKey) {
+      ment.id = { name: 'id', field: 'id', ...composite }
     }
     else if (addressedById(ment)) {
       // The FIELD as well as the descriptor. An entity addressed by id has an
@@ -111,7 +203,7 @@ const fieldTransform: Transform = async function(
       // with neither a field nor an id param — the read-only public APIs the
       // rule above was written for — still get no descriptor, so they still
       // get no id assertions.
-      ment.id = { name: 'id', field: 'id' }
+      ment.id = { name: 'id', field: 'id', ...composite }
     }
 
     msg += ment.name + ' '
@@ -122,6 +214,569 @@ const fieldTransform: Transform = async function(
 
 
 
+// The separator that joins a composite id into one string.
+//
+// A forward slash cannot occur inside a single path segment — a raw `/`
+// would end the segment, and a value that legitimately contains one arrives
+// percent-encoded as `%2F` — so joining on it can never be ambiguous, and
+// splitting on it can never over-split. That is what makes the composite id
+// safe to carry as a single opaque string, which is the property the SDK and
+// Seneca entities are built on.
+const ID_SEP = '/'
+
+// Subfields that conventionally carry the identifying value of a nested
+// object, in preference order. github's repo `owner` is a user object whose
+// identifier is `login`; other specs use `name`, `slug` or `key`. `id` is
+// last: it is the most common name and the least likely to be the value a
+// PATH parameter takes (a path that wanted an id would say so).
+const NESTED_ID_KEYS = ['login', 'slug', 'name', 'key', 'id']
+
+
+// The ops that address ONE record, most authoritative first. Only a
+// tie-break: identityParams compares candidates from all of them.
+const ID_OPS = ['load', 'update', 'patch', 'remove']
+
+
+// The parameters that TOGETHER name one record: the trailing run of
+// ADJACENT variable segments on the addressing route.
+//
+// ADJACENCY IS THE WHOLE TEST, and it is what separates a compound key from
+// ordinary parent/child nesting:
+//
+//   /repos/{owner}/{repo}                     -> owner, repo   COMPOSITE
+//   /api/planet/{planet_id}/moon/{moon_id}    -> moon_id       single
+//   /repos/{owner}/{repo}/pulls/{pull_number} -> pull_number   single
+//
+// A literal segment between two variables names a SUB-COLLECTION, so the
+// earlier variable scopes the later one — `planet_id` says which planet's
+// moons, and `moon_id` alone identifies the moon. Two variables with nothing
+// between them address no sub-collection: neither value names anything on
+// its own, and only the pair identifies a repository.
+//
+// Taking every variable on the path instead was tried first and is wrong on
+// most real specs — it made `moon` (planet_id + moon_id), petstore's `order`,
+// `pet` and `user`, and taxonomy's `domain` and `kingdom` all falsely
+// composite, which the apidef-validate goldens caught immediately. Nested
+// resources are the common shape; compound keys are the exception, and
+// adjacency is the thing that actually distinguishes them.
+//
+// Read from the op that names a single record, never from `list`: a
+// collection route's path params are the entity's parents. A point ending in
+// a literal is a verb ON the record (`.../{number}/merge`) and carries the
+// same variables, so it is a fallback rather than a different answer.
+// Walk back from a point's end, collecting variables until a literal stops
+// the run. That literal is the sub-collection boundary; anything before it
+// scopes this record rather than naming it.
+function trailingVars(point: any): string[] {
+  const segs = ((point?.segments || []) as any[]).filter((s: any) => null != s)
+  const run: string[] = []
+
+  for (let i = segs.length - 1; 0 <= i; i--) {
+    if (null == segs[i].var) {
+      break
+    }
+    run.unshift(String(segs[i].var))
+  }
+
+  return run
+}
+
+
+function identityParams(ment: ModelEntity): string[] {
+  // EVERY ID-BEARING OP AT ONCE, not the first one that offers a candidate.
+  //
+  // These four ops all address a single record, so all four describe the
+  // same identity — but they do not all carry the same routes. gitlab's
+  // `project` has `/api/v4/projects/{id}` under `remove` alone, while its
+  // `load` carries only sub-resources like
+  // `/api/v4/projects/{id}/uploads/{secret}/{filename}`. Returning on the
+  // first op with any candidate therefore made a PROJECT identified by
+  // `secret/filename`. The op order is now only a tie-break.
+  const cands: any[] = []
+
+  for (let o = 0; o < ID_OPS.length; o++) {
+    const mop = (ment as any).op?.[ID_OPS[o]]
+    if (null == mop) {
+      continue
+    }
+
+    // Action points are verbs dispatched by `$action`, not addresses.
+    for (const pt of (mop.points || [])) {
+      if (null != pt?.select?.['$action']) {
+        continue
+      }
+      const run = trailingVars(pt)
+      if (0 === run.length) {
+        continue
+      }
+      cands.push({
+        run,
+        // Segments BEFORE the run: how much parent scope the route needs.
+        scope: ((pt.segments || []).length - run.length),
+        // DOES THE RUN END IN THE RECORD'S OWN KEY? Then it is the
+        // record's address and nothing further is needed.
+        //
+        // This transform RENAMES that parameter to `id`, so a run ending in
+        // it is this port's own statement of what identifies the record —
+        // and the composite inference must not contradict it.
+        // `/gists/{gist_id}` becomes `/gists/{id}` and is a gist;
+        // `/gists/{gist_id}/{sha}` is a REVISION of one, and won on key
+        // length alone, so a gist came out keyed `gist_id/sha` while the
+        // generated SDK's own load match takes the single parameter. The
+        // same contradiction gave cloudsmith's repo and vulnerability
+        // compound keys their SDKs never address them by.
+        //
+        // Deliberately narrow: exactly `id` or an unrenamed `<entity>_id`,
+        // never any `*_id`. `actor_type/actor_id` IS a compound key, and a
+        // looser test breaks it.
+        own: 'id' === run[run.length - 1] ||
+          (ment as any).name + '_id' === run[run.length - 1],
+        order: o,
+      })
+    }
+  }
+
+  // WHICH ROUTE IS THE RECORD'S OWN ADDRESS.
+  //
+  // An entity gathers every route that reads it, and in a large
+  // specification most of those are sub-resources. Three earlier rules were
+  // measured against the validation corpus, and each is wrong:
+  //
+  //   The FIRST route listed gave github's `repo` the single part
+  //   `subject_digest`, from
+  //   `/repos/{owner}/{repo}/attestations/{subject_digest}` — no compound
+  //   key at all, for the entity this feature exists for. Invisible on a
+  //   small spec, where the first item route IS the record's own.
+  //
+  //   The SHORTEST route ending in a variable took cloudsmith's
+  //   `/vulnerabilities/{owner}/` — a LIST of an owner's vulnerabilities —
+  //   and cut a four-part key down to `owner`, dropping three more
+  //   composites. Ending in a variable does not make a route an address.
+  //
+  //   The LONGEST trailing run took
+  //   `/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}` and made a TEAM
+  //   identified by `owner/repo`. A deep sub-resource can carry more
+  //   adjacent variables than the record's own route does.
+  //
+  // What separates them is PARENT SCOPE: the record's own route is the
+  // least-qualified one that names it, and among equally-qualified routes
+  // the one carrying the fullest key. `/repos/{owner}/{repo}` is qualified
+  // by one segment and the attestations route by four; `/teams/{team_id}`
+  // by one and the org-team-repo route by five; cloudsmith's vulnerability
+  // routes are all qualified by one, so the fullest of them wins.
+  const best = cands.reduce((b: any, c: any) => {
+    if (null == b) {
+      return c
+    }
+    if (c.scope !== b.scope) {
+      return c.scope < b.scope ? c : b
+    }
+    if (c.own !== b.own) {
+      return c.own ? c : b
+    }
+    if (c.run.length !== b.run.length) {
+      return b.run.length < c.run.length ? c : b
+    }
+    return c.order < b.order ? c : b
+  }, null)
+
+  return null == best ? [] : best.run
+}
+
+// THE PROPERTY MAPS A RESPONSE COULD BE DESCRIBING, best first.
+//
+// BOTH SPEC DIALECTS. An OpenAPI 3 response carries its schema under
+// `content['application/json']`; a SWAGGER 2 response carries it directly as
+// `schema`. Reading only the first resolved nothing for every Swagger 2 spec
+// in the validation corpus.
+//
+// JSON ONLY, where there is a choice. An operation may declare several media
+// types with different schemas, and field extraction uses the JSON one — so
+// picking whichever came first in source order could infer a path from an XML
+// or binary schema that the actual JSON record does not have.
+//
+// `allOf` IS EXPANDED, because a response that composes its entity that way
+// has neither `properties` nor `items` of its own. field extraction expands
+// it; not doing so here meant the fields were present while the id could not
+// be reconstructed.
+//
+// ONLY THE ENVELOPE IS DESCENDED, via the same `envelopeProp` rule field
+// extraction uses. Descending every object-valued property instead treats an
+// ordinary nested object as a whole record: for `{ slug, metadata: { tenant } }`
+// addressed by `{tenant}/{slug}`, `tenant` resolved to `tenant` rather than
+// `metadata.tenant` — a confidently wrong path, which is worse than no
+// mapping at all.
+//
+// ACTION POINTS ARE SKIPPED, as `identityParams` skips them: an action's
+// response is a verb's result, not a representation of the entity, so a field
+// that happens to appear there says nothing about what a returned record
+// carries.
+function responseCandidates(ment: ModelEntity, def: any): any[] {
+  const out: any[] = []
+  const seen = new Set<any>()
+
+  // Every property map this schema describes, expanding allOf.
+  const propsOf = (schema: any): any[] => {
+    const node = resolveRef(schema, def)
+    if (null == node || seen.has(node)) {
+      return []
+    }
+    seen.add(node)
+
+    if (Array.isArray(node.allOf)) {
+      return node.allOf.flatMap((member: any) => propsOf(member))
+    }
+
+    if (null != node.properties) {
+      return [node.properties]
+    }
+
+    // A bare array response: the record is the item.
+    const items = resolveRef(node.items, def)
+    if (null != items) {
+      return propsOf(items)
+    }
+
+    return []
+  }
+
+  const add = (schema: any, opname: string) => {
+    for (const props of propsOf(schema)) {
+      out.push(props)
+
+      // One level in, but ONLY through the envelope property.
+      const envelope = envelopeProp(props, opname)
+      if (null == envelope) {
+        continue
+      }
+      const inner = resolveRef(props[envelope], def)
+      if (null == inner) {
+        continue
+      }
+      for (const innerProps of propsOf(inner)) {
+        out.push(innerProps)
+      }
+    }
+  }
+
+  for (const opname of ['load', 'list', 'update', 'create']) {
+    const mop = (ment as any).op?.[opname]
+
+    for (const mpoint of (mop?.points || [])) {
+      // An action point's response is not the entity.
+      if (null != mpoint?.select?.['$action']) {
+        continue
+      }
+
+      const path = (def?.paths || {})[mpoint?.orig]
+      const method = String(mpoint?.method || '').toLowerCase()
+      const responses = path?.[method]?.responses || {}
+
+      for (const code of Object.keys(responses)) {
+        if (!/^2/.test(code)) {
+          continue
+        }
+        const resdef = responses[code] || {}
+
+        const content = resdef.content || {}
+        const ctypes = Object.keys(content)
+        // Prefer JSON; fall back to whatever single type is offered.
+        const json = ctypes.find((c: string) => c.includes('json'))
+        if (null != json) {
+          add(content[json]?.schema, opname)
+        }
+        else {
+          for (const ctype of ctypes) {
+            add(content[ctype]?.schema, opname)
+          }
+        }
+
+        // Swagger 2 puts it here.
+        add(resdef.schema, opname)
+      }
+    }
+  }
+
+  return out
+}
+
+
+// A `$ref` followed one hop, or the schema itself. apidef resolves most refs
+// before this stage; this covers the ones that survive on a nested property.
+function resolveRef(schema: any, def: any): any {
+  if (null == schema) {
+    return null
+  }
+  const ref = schema.$ref
+  if ('string' !== typeof ref || !ref.startsWith('#/')) {
+    return schema
+  }
+
+  let node: any = def
+  for (const seg of ref.slice(2).split('/')) {
+    node = node?.[seg]
+    if (null == node) {
+      return null
+    }
+  }
+  return node
+}
+
+
+// The conventional identifying subfield of a property map, or null.
+function conventionalIdKey(props: any): string | null {
+  for (const key of NESTED_ID_KEYS) {
+    const p = props[key]
+    if (null == p) {
+      continue
+    }
+    const t = String(p.type || '')
+    if ('object' !== t && 'array' !== t) {
+      return key
+    }
+  }
+
+  return null
+}
+
+
+// Every name a part might be carried under: the model's name for it, plus the
+// original wire names of any path parameter that was renamed to it.
+function partAliases(ment: ModelEntity, part: string): string[] {
+  const names = new Set<string>([part])
+
+  each((ment as any).op, (mop: any) => {
+    each(mop?.points, (mpoint: any) => {
+      const rename = mpoint?.rename?.param || {}
+      for (const orig of Object.keys(rename)) {
+        if (String(rename[orig]) === part) {
+          names.add(orig)
+        }
+      }
+      for (const arg of (mpoint?.args?.params || [])) {
+        if (null != arg && arg.name === part && null != arg.orig) {
+          names.add(String(arg.orig))
+        }
+      }
+    })
+  })
+
+  return [...names]
+}
+
+
+// Where one part is carried in a given property map, or null.
+//
+// The four rules, in order, each a fact the spec states: a scalar property of
+// that name; the part naming this entity, resolved to `name`; a scalar
+// `<part>_name` / `_login` / `_slug`; or an object property's conventional
+// identifying subfield.
+function resolvePart(
+  ment: ModelEntity,
+  part: string,
+  aliases: string[],
+  props: any,
+  def: any,
+): string | null {
+  if (null == props) {
+    return null
+  }
+
+  const prop = (name: string) => resolveRef(props[name], def)
+  const scalar = (p: any) =>
+    null != p && 'object' !== String(p.type) && 'array' !== String(p.type) &&
+    null == p.properties && null == p.items
+
+  for (const name of aliases) {
+    if (scalar(prop(name))) {
+      return name
+    }
+  }
+
+  if (part === ment.name && scalar(prop('name'))) {
+    return 'name'
+  }
+
+  for (const name of aliases) {
+    for (const suffix of ['_name', '_login', '_slug']) {
+      if (scalar(prop(name + suffix))) {
+        return name + suffix
+      }
+    }
+  }
+
+  for (const name of aliases) {
+    const nested = prop(name)
+    if (null != nested?.properties) {
+      const sub = conventionalIdKey(nested.properties)
+      if (null != sub) {
+        return name + '.' + sub
+      }
+    }
+  }
+
+  return null
+}
+
+
+// WHERE EACH COMPOSITE PART'S VALUE LIVES IN A RESPONSE.
+//
+// The parts are PATH PARAMETER names; a response names its fields whatever it
+// likes. Resolving one to the other is what lets an SDK put an id on a record
+// the API returned, rather than only address a record whose id it was given.
+//
+// The rules, in order, and each of them is a fact about the spec rather than
+// a guess:
+//
+//   1. a scalar field of exactly that name             -> itself
+//   2. the part names this entity, and there is a `name` -> `name`
+//      (`/repos/{owner}/{repo}` on entity `repo`, whose response calls the
+//      repository `name`)
+//   3. a scalar `<part>_name` / `<part>_login` / `<part>_slug`
+//   4. an OBJECT field of that name         -> `<part>.<conventional key>`
+//      (`owner` is a user object; the value is `owner.login`)
+//
+// A part none of these resolve is left OUT. Downstream then knows the id
+// cannot be rebuilt for that entity and can say so, which is better than a
+// confidently wrong id on a real record. guide.aon can state it instead.
+function identityFrom(
+  ment: ModelEntity,
+  parts: string[],
+  def: any,
+): Record<string, string> {
+  // THE RESPONSE SCHEMA IS THE AUTHORITY, not `ment.fields`.
+  //
+  // `ment.fields` is merged across load, create, update and list, so a part
+  // that exists only in a REQUEST BODY appears there too. Resolving against
+  // it recorded such a part in `from` as though a returned record carried it,
+  // and a consumer then rebuilt an id from a property the response never
+  // sends — worse than leaving the part unresolved, which at least says so.
+  //
+  // Candidate property maps, in order: the response's own properties, then
+  // one level into an envelope. A response that wraps the record
+  // (`{ item: {...} }`, `{ data: [ {...} ] }`) states the record's fields one
+  // level in, and searching only the wrapper found nothing.
+  const candidates = responseCandidates(ment, def)
+  const out: Record<string, string> = {}
+
+  for (const part of parts) {
+    // THE WIRE NAME AS WELL AS THE MODEL NAME. `identityParams` reads the
+    // RENAMED parameter off the path segments, while a response keeps its own
+    // casing — so a `tenantKey` renamed to `tenant_key` was looked up under a
+    // name the response does not use, and the mapping was dropped for every
+    // camel-cased or depluralized parameter.
+    const aliases = partAliases(ment, part)
+
+    let found: string | null = null
+
+    for (const props of candidates) {
+      found = resolvePart(ment, part, aliases, props, def)
+      if (null != found) {
+        break
+      }
+    }
+
+    if (null != found) {
+      out[part] = found
+    }
+  }
+
+  return out
+}
+
+
+// Is this model field declared as a string? A composite id is the parts
+// joined, so the field that holds it has to be one.
+function scalarStringField(f: any): boolean {
+  return String(f?.type || '').toUpperCase().includes('STRING')
+}
+
+
+// WHICH PARAMETER IS THE RECORD'S OWN KEY, among several that looked
+// adjacent. The same shape apidef's id handling recognises everywhere else:
+//
+//   1. one named exactly `id`
+//   2. `<entity>_id` — the entity's own id, however the path spells it
+//   3. any `*_id` — an id by name
+//   4. failing all that, the terminal parameter
+//
+// Position is the LAST resort, not the first.
+function singleKeyOf(ment: ModelEntity, parts: string[]): string | undefined {
+  if (0 === parts.length) {
+    return undefined
+  }
+
+  return parts.find((p: string) => 'id' === p)
+    ?? parts.find((p: string) => p === ment.name + '_id')
+    ?? parts.find((p: string) => p.endsWith('_id'))
+    ?? parts[parts.length - 1]
+}
+
+
+// The composite half of the id descriptor, or `{}` for the ordinary case.
+//
+// Emitted ONLY for a genuinely composite id (two or more addressing
+// parameters). A single-parameter entity already round-trips through one
+// `id` and gains nothing from carrying a one-element `parts`, so its
+// descriptor is left exactly as it was — no existing model output moves.
+function compositeId(
+  ment: ModelEntity,
+  gent?: any,
+  def?: any,
+): { parts?: string[], sep?: string, from?: Record<string, string> } {
+  const gid = gent?.id
+  const sep = null != gid?.sep && '' !== String(gid.sep) ? String(gid.sep) : ID_SEP
+
+  // `composite: false` turns the inference off. A boolean rather than an
+  // empty `parts`, because aontu resolves an empty list to nothing and the
+  // key would arrive absent — indistinguishable from never having been set.
+  if (null != gid && false === gid.composite) {
+    // DISABLING COMPOSITE MUST NOT DISABLE THE ID. The correction says these
+    // adjacent parameters are not a compound key; it does not say the record
+    // has no key. Returning a bare `{}` left an entity whose response has no
+    // literal `id` with no descriptor at all — the false positive removed and
+    // nothing identifying the real key.
+    //
+    // WHICH of the adjacent parameters is that key is decided by the same
+    // id-finding rules apidef uses elsewhere, not by position. Taking the
+    // terminal one picked `archive_format` for
+    // `/artifacts/{artifact_id}/{archive_format}` — the modifier, precisely
+    // the false positive the correction exists to undo.
+    return { single: singleKeyOf(ment, identityParams(ment)) } as any
+  }
+
+  // `from` STATED IN guide.aon WINS PER PART, so a spec can correct one
+  // mapping without restating the others — which matters because the
+  // heuristic gets most of them right and the odd one wrong.
+  const withFrom = (parts: string[], usesep: string) => {
+    const derived = identityFrom(ment, parts, def)
+    const stated = null != gid?.from && 'object' === typeof gid.from ? gid.from : {}
+    const from: Record<string, string> = {}
+
+    for (const part of parts) {
+      const say = (stated as any)[part]
+      const use = null != say && '' !== String(say) ? String(say) : derived[part]
+      if (null != use) {
+        from[part] = use
+      }
+    }
+
+    return 0 === Object.keys(from).length ?
+      { parts, sep: usesep } : { parts, sep: usesep, from }
+  }
+
+  if (null != gid && null != gid.parts) {
+    const given = (gid.parts as any[])
+      .filter((p: any) => null != p && '' !== String(p))
+      .map((p: any) => String(p))
+    return 1 < given.length ? withFrom(given, sep) : {}
+  }
+
+  const parts = identityParams(ment)
+  return 1 < parts.length ? withFrom(parts, sep) : {}
+}
+
+
 // True when any of the entity's own operation points declares an `id`
 // parameter — i.e. the API addresses this entity by id, whether or not its
 // response schema declares an id field.