@voxgig/apidef 8.15.2 → 8.16.0

package/src/parse.ts

@@ -132,6 +132,16 @@ async function parseOpenAPI(source: any, _meta?: any) {
 }
 
 
+// Edges decycle cut, so the guide can still count through them; a clone has none.
+const DECYCLED = new WeakMap<object, Map<string, object>>()
+
+
+function decycledChild(holder: any, key: string | number): any {
+  const cut = DECYCLED.get(holder)?.get(String(key))
+  return undefined === cut ? holder[key] : cut
+}
+
+
 function decycle(root: any) {
   // Entry path of each node on the current ancestor chain; presence in this
   // map is what identifies a back-edge. Nodes are removed on the way out, so
@@ -161,6 +171,12 @@ function decycle(root: any) {
 
       const cyclePath = onPath.get(val)
       if (undefined !== cyclePath) {
+        let cuts = DECYCLED.get(node)
+        if (undefined === cuts) {
+          cuts = new Map()
+          DECYCLED.set(node, cuts)
+        }
+        cuts.set(String(key), val)
         node[key] = `[Circular *${cyclePath.join('.')}]`
         continue
       }
@@ -189,54 +205,63 @@ function refSiblings(node: any): any {
 }
 
 
-function addXRefsAndResolve(obj: any, root: any, visited?: WeakSet<any>) {
+function addXRefsAndResolve(
+  obj: any,
+  root: any,
+  visited: WeakSet<any> = new WeakSet(),
+  expanding: Map<any, any> = new Map(),
+) {
   if (!obj || typeof obj !== 'object') return
-  if (!visited) visited = new WeakSet()
   if (visited.has(obj)) return
   visited.add(obj)
 
-  if (Array.isArray(obj)) {
-    for (let i = 0; i < obj.length; i++) {
-      const item = obj[i]
-      if (item && typeof item === 'object') {
-        if (typeof item.$ref === 'string') {
-          const xref = item.$ref
-          const resolved = resolvePointer(root, xref)
-          if (resolved !== undefined) {
-            obj[i] = { ...resolved, ...refSiblings(item), 'x-ref': xref }
-            addXRefsAndResolve(obj[i], root, visited)
-          } else {
-            item['x-ref'] = xref
-            addXRefsAndResolve(item, root, visited)
-          }
-        } else {
-          addXRefsAndResolve(item, root, visited)
-        }
-      }
-    }
-  } else {
-    for (const key of Object.keys(obj)) {
-      const val = obj[key]
-      if (val && typeof val === 'object') {
-        if (typeof val.$ref === 'string') {
-          const xref = val.$ref
-          const resolved = resolvePointer(root, xref)
-          if (resolved !== undefined) {
-            obj[key] = { ...resolved, ...refSiblings(val), 'x-ref': xref }
-            addXRefsAndResolve(obj[key], root, visited)
-          } else {
-            val['x-ref'] = xref
-            addXRefsAndResolve(val, root, visited)
-          }
-        } else {
-          addXRefsAndResolve(val, root, visited)
-        }
+  const keys: (string | number)[] =
+    Array.isArray(obj) ? Array.from(obj.keys()) : Object.keys(obj)
+
+  for (const key of keys) {
+    const val = obj[key]
+    if (val && typeof val === 'object') {
+      if (typeof val.$ref === 'string') {
+        resolveRefSite(obj, key, root, visited, expanding)
+      } else {
+        addXRefsAndResolve(val, root, visited, expanding)
       }
     }
   }
 }
 
 
+function resolveRefSite(
+  holder: any,
+  key: string | number,
+  root: any,
+  visited: WeakSet<any>,
+  expanding: Map<any, any>,
+) {
+  const site = holder[key]
+
+  const inProgress = expanding.get(site)
+  if (undefined !== inProgress) {
+    holder[key] = inProgress
+    return
+  }
+
+  const xref = site.$ref
+  const resolved = resolvePointer(root, xref)
+  if (resolved === undefined) {
+    site['x-ref'] = xref
+    addXRefsAndResolve(site, root, visited, expanding)
+    return
+  }
+
+  const copy = { ...resolved, ...refSiblings(site), 'x-ref': xref }
+  holder[key] = copy
+  expanding.set(site, copy)
+  addXRefsAndResolve(copy, root, visited, expanding)
+  expanding.delete(site)
+}
+
+
 function resolvePointer(root: any, ref: string): any {
   const seen = new Set<string>()
   const siblings: any[] = []
@@ -316,6 +341,7 @@ function validateSource(kind: string, source: any, meta: { file: string }) {
 
 export {
   parse,
+  decycledChild,
 }
 
 

package/src/refcount.ts

@@ -0,0 +1,244 @@
+/* Copyright (c) 2026 Voxgig, MIT License */
+
+import { decycledChild } from './parse'
+
+
+const REFCOUNT_CAP = 1_000_000_000
+
+const ROOT = '\x01ROOT'
+
+const INDEX_RE = /^(0|[1-9]\d*)$/
+
+type Body = Map<string, number>
+
+
+function satAdd(a: number, b: number): number {
+  return Math.min(a + b, REFCOUNT_CAP)
+}
+
+
+function satMul(a: number, w: number): number {
+  if (0 === a || 0 === w) return 0
+  if (a > Math.floor(REFCOUNT_CAP / w)) return REFCOUNT_CAP
+  return a * w
+}
+
+
+function byCodePoint(a: string, b: string): number {
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    const x = a.charCodeAt(i)
+    const y = b.charCodeAt(i)
+    if (x !== y) return codePointRank(x) - codePointRank(y)
+  }
+  return a.length - b.length
+}
+
+
+// Surrogate units sort below U+E000-U+FFFF as UTF-16 but above them by code point.
+function codePointRank(unit: number): number {
+  return unit < 0xD800 ? unit : unit < 0xE000 ? unit + 0x2000 : unit - 0x800
+}
+
+
+function isNode(v: any): boolean {
+  return null != v && 'object' === typeof v
+}
+
+
+function refLabel(v: any): string | undefined {
+  if (!isNode(v) || Array.isArray(v)) return undefined
+  if ('string' === typeof v['x-ref']) return v['x-ref']
+  if (!Object.prototype.hasOwnProperty.call(v, 'x-ref') && 'string' === typeof v.$ref) {
+    return v.$ref
+  }
+  return undefined
+}
+
+
+function hasKid(node: any, key: string): boolean {
+  if (!isNode(node)) return false
+  return Array.isArray(node) ?
+    INDEX_RE.test(key) && Number(key) < node.length :
+    Object.prototype.hasOwnProperty.call(node, key)
+}
+
+
+function hasKids(node: any): boolean {
+  if (!isNode(node)) return false
+  return 0 < (Array.isArray(node) ? node.length : Object.keys(node).length)
+}
+
+
+function kidKeys(node: any): string[] {
+  return Array.isArray(node) ?
+    node.map((_: any, i: number) => String(i)) : Object.keys(node)
+}
+
+
+// Parts join on '\0'. Escaping '\0' and '\x01' keeps keys injective and in part
+// order, and an escape never puts 'R' after '\x01', so no key equals ROOT.
+function nodeKey(label: string, over: string[]): string {
+  return [label, ...over]
+    .map(part => part.replace(/[\0\x01]/g, c => '\0' === c ? '\x01\x01' : '\x01\x02'))
+    .join('\0')
+}
+
+
+// Occurrences of each reference label per use in the resolved spec, where a $ref
+// chain resolves to its first label.
+function countRefs(def: any): Record<string, number> {
+  const targets = new Map<string, any>()
+  const target = (label: string): any => {
+    if (targets.has(label)) return targets.get(label)
+    let t: any = undefined
+    if (label.startsWith('#/')) {
+      t = def
+      for (const raw of label.substring(2).split('/')) {
+        const part = raw.replace(/~1/g, '/').replace(/~0/g, '~')
+        if (!hasKid(t, part)) {
+          t = undefined
+          break
+        }
+        t = decycledChild(t, part)
+      }
+      if (!isNode(t)) t = undefined
+    }
+    targets.set(label, t)
+    return t
+  }
+
+  const same = (a: any, b: any): boolean => {
+    if (isNode(a) && a === b) return true
+    const label = refLabel(a)
+    return undefined !== label && label === refLabel(b)
+  }
+
+  const labelOf = new Map<string, string>()
+  const skipOf = new Map<string, Set<string>>()
+  const found: string[] = []
+
+  const scan = (start: any, skip: Set<string>): Body => {
+    const body: Body = new Map()
+    const expanded = new Set<any>()
+    const stack: any[] = []
+    for (const k of kidKeys(start)) {
+      if ('x-ref' !== k && '$ref' !== k && !skip.has(k)) {
+        stack.push(decycledChild(start, k))
+      }
+    }
+
+    while (0 < stack.length) {
+      const v = stack.pop()
+      if (!isNode(v)) continue
+
+      const label = refLabel(v)
+      if (undefined === label) {
+        // Expanding a shared plain node once per scan is what ends a cycle of them.
+        if (expanded.has(v)) continue
+        expanded.add(v)
+        for (const k of kidKeys(v)) stack.push(decycledChild(v, k))
+        continue
+      }
+
+      const t = target(label)
+      const over: string[] = []
+      for (const k of Object.keys(v)) {
+        if ('x-ref' === k || '$ref' === k) continue
+        const vk = decycledChild(v, k)
+        if (hasKid(t, k)) {
+          const tk = decycledChild(t, k)
+          if (same(vk, tk)) continue
+          if (hasKids(tk)) over.push(k)
+        }
+        stack.push(vk)
+      }
+      over.sort(byCodePoint)
+
+      const node = nodeKey(label, over)
+      if (!labelOf.has(node)) {
+        labelOf.set(node, label)
+        skipOf.set(node, new Set(over))
+        found.push(node)
+      }
+      body.set(node, (body.get(node) ?? 0) + 1)
+    }
+
+    return body
+  }
+
+  const bodies = new Map<string, Body>([[ROOT, scan(def, new Set())]])
+  for (let i = 0; i < found.length; i++) {
+    const node = found[i]
+    const t = target(labelOf.get(node) as string)
+    bodies.set(node, undefined === t ? new Map() : scan(t, skipOf.get(node) as Set<string>))
+  }
+
+  const count = countPaths(bodies)
+
+  const out: Record<string, number> = {}
+  for (const node of found) {
+    const label = labelOf.get(node) as string
+    out[label] = satAdd(out[label] ?? 0, count.get(node) ?? 0)
+  }
+  return out
+}
+
+
+function countPaths(bodies: Map<string, Body>): Map<string, number> {
+  // Code-point order, so both ports cut the same edge of a reference cycle.
+  const successors = (u: string) =>
+    [...(bodies.get(u) as Body).keys()].sort(byCodePoint)
+
+  const onStack = new Set<string>([ROOT])
+  const finished = new Set<string>()
+  const backEdges = new Map<string, Set<string>>()
+  const post: string[] = []
+
+  const stack = [{ node: ROOT, next: successors(ROOT), i: 0 }]
+  while (0 < stack.length) {
+    const frame = stack[stack.length - 1]
+    if (frame.i < frame.next.length) {
+      const v = frame.next[frame.i++]
+      if (onStack.has(v)) {
+        let cut = backEdges.get(frame.node)
+        if (undefined === cut) {
+          cut = new Set()
+          backEdges.set(frame.node, cut)
+        }
+        cut.add(v)
+      }
+      else if (!finished.has(v)) {
+        onStack.add(v)
+        stack.push({ node: v, next: successors(v), i: 0 })
+      }
+    }
+    else {
+      stack.pop()
+      onStack.delete(frame.node)
+      finished.add(frame.node)
+      post.push(frame.node)
+    }
+  }
+
+  const count = new Map<string, number>([[ROOT, 1]])
+  for (let i = post.length - 1; 0 <= i; i--) {
+    const u = post[i]
+    const cu = count.get(u) ?? 0
+    const cut = backEdges.get(u)
+    for (const [v, w] of bodies.get(u) as Body) {
+      if (cut?.has(v)) continue
+      count.set(v, satAdd(count.get(v) ?? 0, satMul(cu, w)))
+    }
+  }
+  return count
+}
+
+
+export {
+  REFCOUNT_CAP,
+  byCodePoint,
+  countRefs,
+  satAdd,
+  satMul,
+}

package/src/transform/field.ts

@@ -509,7 +509,7 @@ function compositeId(
     return { single: singleKeyOf(ment, identityParams(ment)) } as any
   }
 
-  // `from` STATED IN guide.aon WINS PER PART, so a spec can correct one
+  // `from` STATED IN guide.aontu 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) => {

package/src/transform/operation.ts

@@ -27,7 +27,7 @@ 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
+// typo) is dropped WITH A WARNING: guide.aontu 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']

package/src/transform/top.ts

@@ -40,7 +40,7 @@ const topTransform = async function(
   // 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.aon (and
+  // 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)
 

package/src/types.ts

@@ -268,10 +268,10 @@ type GuideEntity = {
   name: string
   orig: string
   // `false` drops the entity downstream (transform/entity.ts). Emitted by
-  // the heuristic for an access-token exchange, and editable in guide.aon —
+  // the heuristic for an access-token exchange, and editable in guide.aontu —
   // which is the ONLY correction surface (ADR-002).
   active?: boolean
-  // Why the heuristic deactivated it, so guide.aon reads as a record of a
+  // Why the heuristic deactivated it, so guide.aontu reads as a record of a
   // decision rather than an unexplained `active: false`.
   why_inactive?: string
   field?: Record<string, GuidePath>

package/src/utility.ts

@@ -1141,7 +1141,7 @@ const CMP_RESULT_VERBS = [
 
 const CMP_PREFIXES = ['get_', 'post_', 'put_', 'delete_', 'patch_']
 
-// A guide node (entity, path or op) is active unless guide.aon explicitly
+// A guide node (entity, path or op) is active unless guide.aontu explicitly
 // says otherwise. `active` has always been declared in the guide model and
 // documented as the escape hatch for a misclassified entity; this is the
 // single place that decides what it means, so entity/flow/operation transforms
@@ -1595,6 +1595,58 @@ function envelopeProp(resprops: any, opname: string): string | null {
 }
 
 
+// What a page may hold beside its records, compared without case, `_` or
+// `-`. Any other property is data, which makes the component a record.
+const ENVELOPE_PAGING_PROPS = new Set([
+  'count', 'total', 'totalcount', 'totalhits', 'totalitems', 'totalpages',
+  'totalresults', 'page', 'pages', 'pagecount', 'pagenumber', 'pagesize',
+  'perpage', 'limit', 'offset', 'cursor', 'next', 'nextcursor', 'nextpage',
+  'nextpagetoken', 'nexttoken', 'previous', 'prev', 'previouscursor',
+  'prevcursor', 'previouspage', 'prevpage', 'hasmore', 'hasnext',
+  'hasprevious', 'object', 'url',
+])
+
+
+function isEnvelopePagingProp(name: string): boolean {
+  return ENVELOPE_PAGING_PROPS.has(name.toLowerCase().replace(/[_-]/g, ''))
+}
+
+
+// The component a response envelope carries: the resolved reference of the
+// record envelopeProp unwraps to. Narrower than envelopeProp, since a record
+// with one structured property passes that test too: an envelope has no `id`,
+// a page holds nothing beside its records but paging, and a single-item
+// envelope holds nothing beside the item.
+function envelopeItemRef(schema: any, opname: string): string | null {
+  const props = schema?.properties
+  const key = envelopeProp(props, opname)
+  if (null == key || null != props.id) {
+    return null
+  }
+
+  const prop = props[key]
+  const islist = propIsList(prop)
+  const rest = keysof(props).filter((k: string) => k !== key)
+  if (islist ? !rest.every(isEnvelopePagingProp) : 0 < rest.length) {
+    return null
+  }
+
+  const item = islist ? prop.items : prop
+  if (!isRecordSchema(item)) {
+    return null
+  }
+
+  const xref = item['x-ref']
+  return 'string' === typeof xref && '' !== xref ? xref : null
+}
+
+
+function isRecordSchema(schema: any): boolean {
+  return null != schema && 'object' === typeof schema && (
+    null != schema.properties || null != schema.allOf || 'object' === schema.type)
+}
+
+
 function untaggedUnionBranches(schema: any): number {
   if (null == schema || 'object' !== typeof schema) {
     return 0
@@ -1757,6 +1809,7 @@ export {
   sortedEntries,
   isEntityWrapperProp,
   envelopeProp,
+  envelopeItemRef,
   closedBodyTransform,
   untaggedUnionBranches,
   scanUntaggedUnion,