@voxgig/apidef 8.12.1 → 8.14.0

package/src/builder/entity/entity.ts

@@ -35,7 +35,8 @@ function resolveEntity(
   each(kit.entity, ((entity: any, entityName: string) => {
     const entityFile = (null == opts.outprefix ? '' : opts.outprefix) + entityName + '.aon'
 
-    let entityJSONIC = formatJSONIC(entity).trim()
+    const { model, relations } = entityAncestorSource(entity)
+    let entityJSONIC = formatJSONIC(model).trim()
     entityJSONIC = entityJSONIC.substring(1, entityJSONIC.length - 1)
 
     const fieldAliasesSrc = fieldAliases(entity)
@@ -45,6 +46,7 @@ function resolveEntity(
       `main: ${KIT}: entity: ${entity.name}: {\n\n` +
       `  alias: field: ${fieldAliasesSrc}\n` +
       entityJSONIC +
+      relations +
       '\n\n}\n'
 
     entityFiles.push({ name: entityFile, src: entitySrc })
@@ -65,6 +67,20 @@ function resolveEntity(
   }
 }
 
+function entityAncestorSource(entity: any): { model: any, relations: string } {
+  const model = { ...entity }
+  const ancestors: string[][] = entity.relations?.ancestors ?? []
+  if (null != entity.relations) {
+    model.relations = { ...entity.relations }
+    delete model.relations.ancestors
+    if (0 === Object.keys(model.relations).length) delete model.relations
+  }
+  const chains = ancestors.map(chain => '    [' + chain.map(name =>
+    'path(' + JSON.stringify('$.main.kit.entity.' + name) + ')').join(' ') + ']')
+  return { model, relations: 0 === chains.length ? '' :
+    '\n  relations: ancestors: [\n' + chains.join('\n') + '\n  ]' }
+}
+
 
 function gcEntityFiles(
   fs: any,
@@ -126,4 +142,5 @@ function fieldAliases(_entity: any): string {
 export {
   resolveEntity,
   gcEntityFiles,
+  entityAncestorSource,
 }

package/src/builder/flow/flowHeuristic01.ts

@@ -81,11 +81,11 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
 
     let num = (i * size(apiEntity.fields) * 10)
     each(apiEntity.fields, (field) => {
-      ent[field.name] =
-        'number' === field.type ? num :
-          'boolean' === field.type ? 0 === num % 2 :
-            'object' === field.type ? {} :
-              'array' === field.type ? [] :
+      ent[field.n] =
+        'number' === field.t ? num :
+          'boolean' === field.t ? 0 === num % 2 :
+            'object' === field.t ? {} :
+              'array' === field.t ? [] :
                 's' + (num.toString(16))
       num++
     })
@@ -108,9 +108,9 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
     const point = findMainLoadPoint(entop.load)
 
     // Get additional required match properties
-    each(point?.args.params, (param: any) => {
-      if (param.required) {
-        let ancestorName = param.name
+    each(point?.g.params, (param: any) => {
+      if (param.r) {
+        let ancestorName = param.n
         let ancestorEntity = apimodel.main.api.entity[ancestorName]
 
         if (null == ancestorEntity) {
@@ -122,10 +122,10 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
           flow.model.param[`${model.NAME}_TEST_${ancestorEntity.NAME}_ENTID`] = {
             [ancestorEntity.name + '01']: ancestorEntity.NAME + '01'
           }
-          am[param.name] =
+          am[param.n] =
             `\`dm$=p.${model.NAME}_TEST_${ancestorEntity.NAME}_ENTID.${ancestorEntity.name}01\``
 
-          data[`${nom(apiEntity, 'NAME')}01`][param.name] = ancestorEntity.NAME + '01'
+          data[`${nom(apiEntity, 'NAME')}01`][param.n] = ancestorEntity.NAME + '01'
         }
       }
     })
@@ -197,7 +197,7 @@ function resolveBasicEntityFlow(ctx: any, entity: any) {
 
 
 function findMainLoadPoint(op: ModelOp): ModelPoint | undefined {
-  let cands = op.points.filter(a => 'id' === getelem(a.segments, -1)?.var)
+  let cands = op.points.filter(a => 'id' === getelem(a.s, -1)?.var)
   return cands[0]
 }
 
@@ -207,12 +207,12 @@ function makeUpdateData(name: string, apiEntity: any, flow: any, id: string) {
   const data = flow.model.test.entity[apiEntity.name]
 
   const dataFields =
-    each(apiEntity.field).filter(f => 'id' !== f.name && !f.name.includes('_id'))
-  const stringFields = each(dataFields).filter(f => 'string' === f.type)
+    each(apiEntity.fields).filter(f => 'id' !== f.n && !f.n.includes('_id'))
+  const stringFields = each(dataFields).filter(f => 'string' === f.t)
 
   if (0 < size(stringFields)) {
     const f = stringFields[0]
-    ud[f.name] = data[id][f.name] + '-`$WHEN`'
+    ud[f.n] = data[id][f.n] + '-`$WHEN`'
   }
 
   return ud

package/src/model.ts

@@ -61,17 +61,18 @@ type ModelFieldOp = {
 
 
 type ModelField = {
-  name: string
-  type: any
-  req: boolean
+  n: string
+  h: string
+  t: any
+  r: boolean
   op: Partial<Record<OpName, ModelFieldOp>>
 
-  short?: string
+  sh?: string
 
-  readOnly?: boolean
-  writeOnly?: boolean
-  deprecated?: boolean
-  format?: string
+  ro?: boolean
+  wo?: boolean
+  de?: boolean
+  fo?: string
   union?: {
     count: number
     branches: number
@@ -80,18 +81,14 @@ type ModelField = {
 }
 
 
-// Operation argument/parameter definition.
-// `example` captures a value the spec advertises (parameter `example`,
-// the first entry of `examples`, or `schema.example`/`schema.default`).
-// Test generators use this for required params in live test setup so the
-// generated request actually satisfies the API contract.
+// `ex` holds an advertised parameter example or schema default.
 type ModelArg = {
-  name: string
-  orig: string
-  type: any
-  kind: ArgKind
-  reqd: boolean
-  example?: any
+  n: string
+  or?: string
+  t: any
+  k: ArgKind
+  r: boolean
+  ex?: any
 }
 
 
@@ -133,29 +130,30 @@ type ModelPathSegment = {
 
 
 type ModelPoint = {
-  contract?: { version: number, id: string, source: string, json: string }
-  orig: string
-  kind?: PointKind
-  graphql?: ModelGraphql
-  method: MethodName
-  segments: ModelPathSegment[]
-  rename: Partial<{
+  co?: { version: 2, id: string, source: string }
+  li?: boolean | Record<string, any>
+  o: string
+  k?: PointKind
+  gq?: ModelGraphql
+  m: MethodName
+  s: ModelPathSegment[]
+  r: Partial<{
     param: Record<string, string>
     query: Record<string, string>
     header: Record<string, string>
     cookie: Record<string, string>
   }>
-  args: Partial<{
+  g: Partial<{
     params: ModelArg[]
     query: ModelArg[]
     header: ModelArg[]
     cookie: ModelArg[]
   }>
-  transform: {
+  t: {
     req?: any
     res?: any
   }
-  select: {
+  q: {
     exist: string[]
     $action?: string
   }
@@ -173,7 +171,7 @@ type ModelEntity = {
   Name?: string
   NAME?: string
   op: ModelOpMap
-  fields: ModelField[]
+  fields: Record<string, ModelField>
   id?: {
     name: string
     field: string
@@ -197,7 +195,7 @@ type ModelEntityFlow = {
 // Per-step input cluster. Test-generators name the variables they emit by
 // reading these slots, falling back to derived defaults. All fields are
 // optional — `newFlowStep` in transform/flowstep.ts guarantees the input
-// object itself exists, so consumers don't need to null-check `step.input`.
+// object itself exists, so consumers don't need to null-check `step.i`.
 type ModelEntityFlowStepInput = {
   ref?: string
   entvar?: string
@@ -226,12 +224,13 @@ type ModelEntityFlowStepSpec = {
 
 
 type ModelEntityFlowStep = {
-  op: OpName
-  input: ModelEntityFlowStepInput
-  match: Record<string, any>
-  data: Record<string, any>
-  spec: ModelEntityFlowStepSpec[]
-  valid: ModelEntityFlowStepValidator[]
+  a?: boolean
+  o: OpName
+  i: ModelEntityFlowStepInput
+  m: Record<string, any>
+  d: Record<string, any>
+  s: ModelEntityFlowStepSpec[]
+  v: ModelEntityFlowStepValidator[]
 }
 
 

package/src/resolved.ts

@@ -2,7 +2,22 @@
 
 // See docs/design/resolved-spec-capability.md
 
-import { graphqlInputTypes } from './transform/contract'
+// An operation needs its argument types, including recursive input objects.
+// Output types are represented by the field and generated invocation selection;
+// copying the entire connected output graph per operation is quadratic in API size.
+function graphqlInputTypes(field: any, types: any): any {
+  const out: any = {}
+  function visit(name: string) {
+    if (!types[name] || Object.prototype.hasOwnProperty.call(out, name)) return
+    const type = types[name]
+    out[name] = type
+    if (type.kind === 'INPUT_OBJECT') {
+      for (const child of Object.values(type.fields || {}) as any[]) visit(child.type)
+    }
+  }
+  for (const arg of field.args || []) visit(arg.type)
+  return out
+}
 
 
 const METHODS = [
@@ -16,6 +31,8 @@ type OperationFacts = {
 }
 
 
+type OperationSelector = { entity: string, op: string }
+
 type ResolvedSpec = {
   version: 1
   kind: string
@@ -24,16 +41,14 @@ type ResolvedSpec = {
   // during parse, so a consumer reading the file itself would miss lookups.
   def: any
 
-  operation(method: string, path: string): OperationFacts | undefined
+  operation(method: string, path: string, selector?: OperationSelector): OperationFacts | undefined
 }
 
 
-// The single definition of a resolved operation, shared by contractTransform
-// and by consumers of the capability, so the two cannot disagree.
-function operationFacts(def: any, point: { method: string, orig: string }): OperationFacts | undefined {
-  const path = def?.paths?.[point.orig]
-  const method = path?.[String(point.method).toLowerCase()]
-  const graphql = def?.query?.[point.orig] || def?.mutation?.[point.orig]
+function operationFacts(def: any, point: { m: string, o: string }): OperationFacts | undefined {
+  const path = def?.paths?.[point.o]
+  const method = path?.[String(point.m).toLowerCase()]
+  const graphql = def?.query?.[point.o] || def?.mutation?.[point.o]
 
   if (!method && !graphql) return undefined
 
@@ -67,21 +82,21 @@ function operationFacts(def: any, point: { method: string, orig: string }): Oper
 }
 
 
-// Every described operation, keyed 'METHOD path' as `point.contract.id` is.
+// Every described operation, keyed 'METHOD path' as `point.co.id` is.
 function operationIndex(def: any): { [id: string]: OperationFacts } {
   const out: { [id: string]: OperationFacts } = {}
 
   for (const path of Object.keys(def?.paths || {})) {
     for (const method of METHODS) {
       if (null == def.paths[path]?.[method]) continue
-      const facts = operationFacts(def, { method, orig: path })
+      const facts = operationFacts(def, { m: method, o: path })
       if (facts) out[method.toUpperCase() + ' ' + path] = facts
     }
   }
 
   for (const kind of ['query', 'mutation']) {
     for (const field of Object.keys(def?.[kind] || {})) {
-      const facts = operationFacts(def, { method: 'POST', orig: field })
+      const facts = operationFacts(def, { m: 'POST', o: field })
       if (facts) out['POST ' + field] = facts
     }
   }
@@ -90,20 +105,49 @@ function operationIndex(def: any): { [id: string]: OperationFacts } {
 }
 
 
-function makeResolved(kind: string, def: any): ResolvedSpec {
+function operationGuide(guide: any, method: string, path: string, graphql: boolean,
+  selector?: OperationSelector): any {
+  const matches: any[] = []
+  for (const [entityName, entity] of Object.entries(guide?.entity || {}) as any) {
+    if (selector && selector.entity !== entityName) continue
+    const ops = entity[graphql ? 'field' : 'path']?.[path]?.op || {}
+    for (const [opName, op] of Object.entries(ops) as any) {
+      if (selector && selector.op !== opName) continue
+      if (op.method && op.method.toUpperCase() !== method.toUpperCase()) continue
+      if (op.contract !== undefined || op.live !== undefined) matches.push(op)
+    }
+  }
+  if (matches.length > 1) {
+    throw new Error('Ambiguous operation guide for ' + method + ' ' + path + '; select entity and op')
+  }
+  return matches[0]
+}
+
+function makeResolved(kind: string, def: any, guide: () => any = () => undefined): ResolvedSpec {
   return {
     version: 1,
     kind,
     def,
-    operation: (method: string, path: string) =>
-      operationFacts(def, { method, orig: path }),
+    operation: (method: string, path: string, selector?: OperationSelector) => {
+      const facts = operationFacts(def, { m: method, o: path })
+      if (!facts) return undefined
+      const op = operationGuide(guide(), method, path, facts.protocol === 'graphql', selector)
+      for (const key of ['requestBody', 'responses', 'parameters', 'security']) {
+        if (op?.contract?.[key] !== undefined) {
+          facts[key] = op.contract[key]
+          ;(facts.factSources ??= {})[key] = 'guide'
+        }
+      }
+      if (op?.live !== undefined) facts.live = op.live
+      return facts
+    },
   }
 }
 
 
 // Tolerates a missing context: apidef also runs outside a model build.
-function publishResolved(ctx: any, kind: string, def: any): ResolvedSpec {
-  const resolved = makeResolved(kind, def)
+function publishResolved(ctx: any, kind: string, def: any, guide?: () => any): ResolvedSpec {
+  const resolved = makeResolved(kind, def, guide)
   if (null != ctx && 'object' === typeof ctx) {
     ctx.state = ctx.state || {}
     ctx.state.apidef = { ...(ctx.state.apidef || {}), resolved }
@@ -114,7 +158,7 @@ function publishResolved(ctx: any, kind: string, def: any): ResolvedSpec {
 
 function resolvedSpec(carrier: any): ResolvedSpec | undefined {
   if (null == carrier || 'object' !== typeof carrier) return undefined
-  return carrier.state?.apidef?.resolved ??
+  return carrier.resolved ?? carrier.ctx?.resolved ?? carrier.state?.apidef?.resolved ??
     carrier.ctx?.state?.apidef?.resolved ??
     carrier.apidef?.resolved ??
     undefined
@@ -122,6 +166,7 @@ function resolvedSpec(carrier: any): ResolvedSpec | undefined {
 
 
 export type {
+  OperationSelector,
   OperationFacts,
   ResolvedSpec,
 }

package/src/transform/args.ts

@@ -41,7 +41,7 @@ const argsTransform: Transform = async function(
       each(mop.points, (mpoint: ModelPoint) => {
         const argdefs: ParameterDef[] = []
 
-        if ('graphql' === mpoint.kind) {
+        if ('graphql' === mpoint.k) {
           // GraphQL root-field arguments become 'param' args, so the existing
           // arg machinery (select.exist matching, request typing, test
           // generation) works on them unchanged. Input-object arguments are
@@ -64,10 +64,10 @@ const argsTransform: Transform = async function(
           }
         }
         else {
-          const pathdef: PathDef = def.paths[mpoint.orig]
+          const pathdef: PathDef = def.paths[mpoint.o]
           argdefs.push(...((pathdef as any)?.parameters ?? []))
 
-          const opdef: MethodDef = (pathdef as any)?.[mpoint.method.toLowerCase()]
+          const opdef: MethodDef = (pathdef as any)?.[mpoint.m.toLowerCase()]
           argdefs.push(...(opdef?.parameters ?? []))
         }
 
@@ -85,8 +85,8 @@ const argsTransform: Transform = async function(
 
 // Locate the normalised root-field descriptor a GraphQL point came from.
 function graphqlFieldDef(def: any, mpoint: ModelPoint): any {
-  const field = mpoint.graphql?.field ?? mpoint.orig
-  return 'mutation' === mpoint.graphql?.optype ?
+  const field = mpoint.gq?.field ?? mpoint.o
+  return 'mutation' === mpoint.gq?.optype ?
     def.mutation?.[field] : def.query?.[field]
 }
 
@@ -100,7 +100,7 @@ function gqlScalarType(typeName: string): string | undefined {
 }
 
 
-const ARG_KIND: Record<string, ModelArg["kind"]> = {
+const ARG_KIND: Record<string, ModelArg["k"]> = {
   'query': 'query',
   'header': 'header',
   'path': 'param',
@@ -122,11 +122,11 @@ function resolveArgs(
       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` +
+          ` path=${mpoint.o} 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,
+        path: mpoint.o,
         op: mop.name,
       })
       return
@@ -136,35 +136,35 @@ function resolveArgs(
     // Rename map can be keyed by either the spec original (camelCase) or by
     // the snakified form depending on which path went through heuristic01.
     // Try both before falling through to `orig`.
-    const renameMap = mpoint.rename[kind]
+    const renameMap = mpoint.r[kind]
     const name = renameMap?.[specName] ?? renameMap?.[orig] ?? orig
     const marg: ModelArg = {
-      name,
-      orig,
-      type: inferFieldType(name, validator(argdef.schema?.type)),
-      kind,
-      reqd: !!argdef.required
+      n: name,
+      or: orig,
+      t: inferFieldType(name, validator(argdef.schema?.type)),
+      k: kind,
+      r: !!argdef.required
     }
 
     const example = resolveArgExample(argdef)
     if (undefined !== example) {
-      marg.example = example
+      marg.ex = example
     }
 
     if (argdef.nullable) {
-      marg.type = ['`$ONE`', '`$NULL`', marg.type]
+      marg.t = ['`$ONE`', '`$NULL`', marg.t]
     }
 
-    const argsKey = (marg.kind === 'param' ? 'params' : marg.kind) as keyof typeof mpoint.args
-    let kindargs = (mpoint.args[argsKey] = mpoint.args[argsKey] ?? [])
+    const argsKey = (marg.k === 'param' ? 'params' : marg.k) as keyof typeof mpoint.g
+    let kindargs = (mpoint.g[argsKey] = mpoint.g[argsKey] ?? [])
     kindargs.push(marg)
     touchedKeys.add(argsKey)
   })
 
   // Sort once after all args are collected
-  const cmp = (a: ModelArg, b: ModelArg) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+  const cmp = (a: ModelArg, b: ModelArg) => a.n < b.n ? -1 : a.n > b.n ? 1 : 0
   for (const key of touchedKeys) {
-    mpoint.args[key as keyof typeof mpoint.args]?.sort(cmp)
+    mpoint.g[key as keyof typeof mpoint.g]?.sort(cmp)
   }
 }
 

package/src/transform/clean.ts

@@ -1,5 +1,6 @@
 
 import type { TransformResult, Transform } from '../transform'
+import { KIT } from '../types'
 
 import { walk, isempty, isnode, ismap, islist } from '@voxgig/struct'
 
@@ -54,6 +55,10 @@ const cleanTransform: Transform = async function(
 
   ctx.apimodel = cur[0]
 
+  for (const entity of Object.values(ctx.apimodel.main?.[KIT]?.entity ?? {}) as any[]) {
+    entity.fields ??= {}
+  }
+
   return { ok: true, msg: 'clean' }
 }
 

package/src/transform/contract.ts

@@ -1,89 +1,24 @@
 // Point contracts. See docs/design/resolved-spec-capability.md
 import type { Transform } from '../transform'
 
-import { operationFacts } from '../resolved'
-
-
-export function contractJSON(value: any): string {
-  function walk(root: any, base: string): any {
-    // One memo per fact, so refs stay local to it.
-    const seen = new Map<any, string>()
-    function copy(v: any, path: string): any {
-      if (v === null || typeof v !== 'object') return v
-      if (seen.has(v)) return { $ref: seen.get(v) }
-      seen.set(v, path)
-      const out: any = Array.isArray(v) ? v.map((item, i) => copy(item, path + '/' + i)) : {}
-      if (!Array.isArray(v)) for (const k of Object.keys(v).sort()) {
-        if (!k.endsWith('$') && !k.startsWith('x-') && undefined !== v[k]) out[k] = copy(v[k], path + '/' + k.replace(/~/g, '~0').replace(/\//g, '~1'))
-      }
-      return out
-    }
-    return copy(root, base)
-  }
-
-  if (null === value || 'object' !== typeof value || Array.isArray(value)) {
-    return JSON.stringify(walk(value, '#'))
-  }
-
-  const out: any = {}
-  for (const k of Object.keys(value).sort()) {
-    if (k.endsWith('$') || k.startsWith('x-') || undefined === value[k]) continue
-    out[k] = walk(value[k], '#/' + k.replace(/~/g, '~0').replace(/\//g, '~1'))
-  }
-  return JSON.stringify(out)
-}
-
-// An operation needs its argument types, including recursive input objects.
-// Output types are represented by the field and generated invocation selection;
-// copying the entire connected output graph per operation is quadratic in API size.
-export function graphqlInputTypes(field: any, types: any): any {
-  const out: any = {}
-  function visit(name: string) {
-    if (!types[name] || Object.prototype.hasOwnProperty.call(out, name)) return
-    const type = types[name]
-    out[name] = type
-    if (type.kind === 'INPUT_OBJECT') {
-      for (const child of Object.values(type.fields || {}) as any[]) visit(child.type)
-    }
-  }
-  for (const arg of field.args || []) visit(arg.type)
-  return out
-}
-
 export const contractTransform: Transform = async (ctx: any) => {
   const def = ctx.def || {}
   for (const entity of Object.values(ctx.apimodel.main.kit.entity || {}) as any[]) {
     for (const op of Object.values(entity.op || {}) as any[]) {
       for (const point of op?.points || []) {
-        const path = def.paths?.[point.orig]
-        const method = path?.[point.method.toLowerCase()]
-        const graphql = def.query?.[point.orig] || def.mutation?.[point.orig]
+        const path = def.paths?.[point.o]
+        const method = path?.[point.m.toLowerCase()]
+        const graphql = def.query?.[point.o] || def.mutation?.[point.o]
         if (!method && !graphql) continue
-        const facts: any = operationFacts(def, point)
-        if (null == facts) continue
-
-        // A property of the point, not of the definition.
-        if (graphql) facts.invocation = point.graphql
-        const guideOp = ctx.guide?.entity?.[entity.name]?.[graphql ? 'field' : 'path']?.[point.orig]?.op?.[op.name]
+        const guideOp = ctx.guide?.entity?.[entity.name]?.[graphql ? 'field' : 'path']?.[point.o]?.op?.[op.name]
         const hint = guideOp?.live
-        for (const key of ['requestBody', 'responses', 'parameters', 'security']) {
-          if (guideOp?.contract?.[key] !== undefined) {
-            facts[key] = guideOp.contract[key]
-            ;(facts.factSources ??= {})[key] = 'guide'
-          }
-        }
         if (hint !== undefined) {
-          facts.live = hint
-          point.live = hint
+          point.li = hint
         }
         // Identity only; facts come from the capability. See
         // docs/design/resolved-spec-capability.md
-        point.contract = { version: 1, id: point.method + ' ' + point.orig,
+        point.co = { version: 2, id: point.m + ' ' + point.o,
           source: graphql ? 'graphql' : def.swagger ? 'swagger2' : 'openapi3' }
-
-        if (ctx.opts?.contractJson) {
-          point.contract.json = contractJSON(facts)
-        }
       }
     }
   }

package/src/transform/entity.ts

@@ -59,7 +59,7 @@ const entityTransform: Transform = async function(
     const modelent: ModelEntity = {
       name: entname,
       op: {},
-      fields: [],
+      fields: {},
       relations,
     }
 
@@ -68,9 +68,20 @@ const entityTransform: Transform = async function(
     msg += guideEntity.name + ' '
   })
 
+  filterEntityAncestors(kit.entity)
   return { ok: true, msg }
 }
 
+function filterEntityAncestors(entities: Record<string, any>) {
+  for (const [name, entity] of Object.entries(entities)) {
+    if (null == entity.relations) continue
+    entity.relations.ancestors = (entity.relations.ancestors ?? [])
+      .map((chain: string[]) => chain.filter(ancestor => ancestor !== name &&
+        Object.prototype.hasOwnProperty.call(entities, ancestor)))
+      .filter((chain: string[]) => 0 < chain.length)
+  }
+}
+
 
 // Move "/X" paths onto the entity that owns "/X/{id}" or "/X/{id}/sub".
 // Only acts when the path "/X" sits on a different entity than the
@@ -301,6 +312,7 @@ function suffix(p: string[], c: string[]): boolean {
 
 
 export {
+  filterEntityAncestors,
   resolvePathList,
   buildRelations,
   entityTransform,