@voxgig/apidef 8.11.0 → 8.12.1

package/src/parse/graphql.ts

@@ -1,23 +1,5 @@
 /* Copyright (c) 2024-2026 Voxgig, MIT License */
 
-// GraphQL ingestion: normalise an SDL document or an introspection result
-// into the plain `def` structure the guide and transform stages consume.
-//
-// The OpenAPI parser hands downstream stages the spec object itself, with
-// `$ref`s resolved in place. GraphQL has no equivalent literal document, so
-// this builds an explicit graph instead:
-//
-//   def.types    — every named type, keyed by type name
-//   def.query    — root Query fields, keyed by field name
-//   def.mutation — root Mutation fields, keyed by field name
-//   def.servers  — synthesised from the `endpoint` option (a schema carries
-//                  no deployment URL, but transform/top.ts requires one)
-//   def.info     — synthesised; SDL has no info block
-//
-// Type references are held as NAME STRINGS, never object pointers, so the
-// result is acyclic and JSON-serialisable by construction — GraphQL type
-// graphs are freely recursive (Issue.team.issues), and apidef writes
-// `<def>.full.json` under the debug flag.
 
 import { relativizePath } from '../utility'
 
@@ -114,8 +96,6 @@ function asIntrospection(source: string): any {
 }
 
 
-// Render a type reference to its GraphQL source form ('[Issue!]!') and its
-// named form ('Issue'), plus the required/list flags the classifier keys on.
 function describeType(G: any, gtype: any) {
   const gqltype = String(gtype)
   const named = G.getNamedType(gtype)
@@ -241,11 +221,6 @@ function rootFields(G: any, gtype: any): Record<string, GqlField> {
 }
 
 
-// Parse a GraphQL schema (SDL text or introspection JSON) into `def`.
-//
-// `opts.endpoint` is REQUIRED: a schema declares no deployment URL, but a
-// usable SDK needs a base URL and transform/top.ts fails the build without
-// `servers[0].url`.
 async function parseGraphQL(
   source: string,
   meta: { file: string },

package/src/parse.ts

@@ -103,7 +103,6 @@ async function parseOpenAPI(source: any, _meta?: any) {
     )
   }
 
-  // Ensure components exists (Redocly used to add this automatically)
   if (null == parsed.components) {
     parsed.components = {}
   }
@@ -121,6 +120,9 @@ async function parseOpenAPI(source: any, _meta?: any) {
     parsed.paths = cleaned
   }
 
+  // See docs/design/derived-names.md
+  normalizeColonPathParams(parsed, _meta)
+
   // Single-pass: add x-ref properties and resolve $ref pointers together.
   addXRefsAndResolve(parsed, parsed)
 
@@ -130,22 +132,6 @@ async function parseOpenAPI(source: any, _meta?: any) {
 }
 
 
-// Break reference cycles so the parsed spec stays JSON-serializable, WITHOUT
-// destroying the structure sharing that $ref inlining deliberately creates.
-//
-// @voxgig/util's decircular() rebuilds the tree — it allocates a fresh object
-// per *visit*, so a component reachable by k distinct paths is copied k times
-// and the result is the tree-expansion of the DAG, size O(fanout^depth). That
-// is catastrophic on exactly the shape real specs have (components reused
-// across nesting levels): a 2.3 KB spec with 12 levels and 3 refs per level
-// expanded to a 172 MB model, and 13 levels exhausted a 2 GB heap.
-//
-// Cycles are real here — inlining a self-referential schema makes the copy's
-// `properties` the same object as the original's, so the copy contains
-// itself — so they still have to be cut. This does it in place: only the edge
-// that closes a cycle is replaced (with decircular's marker string, so the
-// output shape is unchanged), every other node is visited exactly once and
-// left shared. Linear in the number of distinct nodes.
 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
@@ -160,11 +146,6 @@ function decycle(root: any) {
     if (null == node || 'object' !== typeof node) return
     if (done.has(node)) return
 
-    // The YAML parser hands back null-prototype objects. decircular() used to
-    // launder them into plain objects as a side effect of rebuilding the tree;
-    // parse()'s result is public, so keep that contract (callers reasonably
-    // expect `hasOwnProperty` etc. on a parsed spec) rather than leaking the
-    // parser's internal shape now that nothing is rebuilt.
     if (!Array.isArray(node) && null === Object.getPrototypeOf(node)) {
       Object.setPrototypeOf(node, Object.prototype)
     }
@@ -198,21 +179,6 @@ function decycle(root: any) {
 }
 
 
-// Single-pass tree walk that:
-// 1. Preserves original $ref values as x-ref
-// 2. Resolves $ref JSON pointers in-place
-//
-// NOTE: resolution inlines a shallow copy of the target ({ ...resolved }),
-// so multiple references to the same component share that component's
-// nested child objects. Downstream consumers must therefore treat the
-// resolved schema as read-only — mutating an inlined sub-object would leak
-// across every site that referenced the same component. (A deep clone is
-// deliberately avoided: schemas can be self-referential, which would make
-// cloning non-terminating.)
-// Keywords sitting beside a `$ref` on the *referring* node. OpenAPI 3.1 and
-// JSON Schema 2020-12 both allow them (`description`, `required`,
-// constraints, ...) and they still apply, so inlining must not drop them.
-// Applied over the resolved target, so the local statement wins.
 function refSiblings(node: any): any {
   const out: any = {}
   for (const k of Object.keys(node)) {
@@ -271,27 +237,8 @@ function addXRefsAndResolve(obj: any, root: any, visited?: WeakSet<any>) {
 }
 
 
-// Follow a JSON pointer like "#/components/schemas/Planet".
-//
-// Alias components — `Foo: { $ref: '#/components/schemas/Bar' }` — are a
-// normal OpenAPI idiom, so a pointer can land on another bare $ref node.
-// Follow the chain to its end rather than returning the intermediate: the
-// caller inlines `{ ...resolved }`, and a `$ref` *string* key in that spread
-// is never followed by the object-valued recursion in addXRefsAndResolve, so
-// stopping early yields a schema with no properties and every field is
-// silently dropped. Whether that happened used to depend on whether `paths`
-// or `components` came first in the document, because resolution reads a root
-// the same walk is still mutating.
-//
-// `seen` holds pointer strings (not object identities) so a self- or
-// mutually-referential alias cycle terminates instead of looping forever.
 function resolvePointer(root: any, ref: string): any {
   const seen = new Set<string>()
-  // Keywords sitting beside a `$ref` along the chain, outermost first.
-  // OpenAPI 3.1 / JSON Schema 2020-12 allow `$ref` to carry siblings
-  // (`description`, `required`, constraints, ...) and they still apply, so
-  // following the chain must not discard them. Merged onto the final target
-  // below, outermost last so the most specific alias wins.
   const siblings: any[] = []
   let current: any = undefined
   let pointer = ref
@@ -370,3 +317,61 @@ function validateSource(kind: string, source: any, meta: { file: string }) {
 export {
   parse,
 }
+
+
+const METHODS = [
+  'get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'
+]
+
+
+// Rewrite `/a/:b/c` to `/a/{b}/c`, for a `:b` the path or one of its
+// operations declares `in: path`. See docs/design/derived-names.md
+function normalizeColonPathParams(parsed: any, meta?: any) {
+  if (null == parsed.paths || 'object' !== typeof parsed.paths) return
+
+  const renamed: string[] = []
+  const out: Record<string, any> = {}
+
+  for (const [path, item] of Object.entries<any>(parsed.paths)) {
+    if (!path.includes('/:')) {
+      out[path] = item
+      continue
+    }
+
+    // Every `in: path` name this path knows about: the path-level parameters
+    // plus each operation's own.
+    const declared = new Set<string>()
+    const collect = (params: any) => {
+      if (!Array.isArray(params)) return
+      for (const param of params) {
+        if (param && 'path' === param.in && 'string' === typeof param.name) {
+          declared.add(param.name)
+        }
+      }
+    }
+    if (null != item) {
+      collect(item.parameters)
+      for (const method of METHODS) {
+        if (null != item[method]) collect(item[method].parameters)
+      }
+    }
+
+    const next = path.split('/').map((seg) =>
+      seg.startsWith(':') && declared.has(seg.slice(1)) ? '{' + seg.slice(1) + '}' : seg
+    ).join('/')
+
+    if (next !== path) renamed.push(path)
+    out[next] = item
+  }
+
+  parsed.paths = out
+
+  if (0 < renamed.length && null != meta?.log?.info) {
+    meta.log.info({
+      point: 'path-colon-params',
+      count: renamed.length,
+      note: 'rewrote ' + renamed.length + ' colon-style path parameter(s) to' +
+        ' OpenAPI brace form, e.g. ' + renamed[0]
+    })
+  }
+}

package/src/resolved.ts

@@ -0,0 +1,136 @@
+/* Copyright (c) 2024-2026 Voxgig Ltd, MIT License */
+
+// See docs/design/resolved-spec-capability.md
+
+import { graphqlInputTypes } from './transform/contract'
+
+
+const METHODS = [
+  'get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'
+]
+
+
+type OperationFacts = {
+  protocol: 'http' | 'graphql'
+  [key: string]: any
+}
+
+
+type ResolvedSpec = {
+  version: 1
+  kind: string
+
+  // The PARSED definition, not the bytes on disk: path keys are normalised
+  // during parse, so a consumer reading the file itself would miss lookups.
+  def: any
+
+  operation(method: string, path: string): 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]
+
+  if (!method && !graphql) return undefined
+
+  const facts: any = { protocol: graphql ? 'graphql' : 'http' }
+
+  if (graphql) {
+    facts.field = graphql
+    facts.types = graphqlInputTypes(graphql, def.types || {})
+    facts.typesScope = 'inputs'
+    return facts
+  }
+
+  for (const key of ['operationId', 'requestBody', 'responses', 'consumes', 'produces']) {
+    if (undefined !== method[key]) facts[key] = method[key]
+  }
+
+  // A path item may declare parameters shared by every operation under it.
+  facts.parameters = [...(path.parameters || []), ...(method.parameters || [])]
+
+  facts.security = method.security ?? def.security
+  facts.securitySource = method.security !== undefined ? 'operation' :
+    def.security !== undefined ? 'definition' : 'unspecified'
+
+  // swagger2 names this `securityDefinitions`.
+  facts.securitySchemes = def.components?.securitySchemes ?? def.securityDefinitions
+
+  facts.consumes ??= def.consumes
+  facts.produces ??= def.produces
+
+  return facts
+}
+
+
+// Every described operation, keyed 'METHOD path' as `point.contract.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 })
+      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 })
+      if (facts) out['POST ' + field] = facts
+    }
+  }
+
+  return out
+}
+
+
+function makeResolved(kind: string, def: any): ResolvedSpec {
+  return {
+    version: 1,
+    kind,
+    def,
+    operation: (method: string, path: string) =>
+      operationFacts(def, { method, orig: path }),
+  }
+}
+
+
+// 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)
+  if (null != ctx && 'object' === typeof ctx) {
+    ctx.state = ctx.state || {}
+    ctx.state.apidef = { ...(ctx.state.apidef || {}), resolved }
+  }
+  return resolved
+}
+
+
+function resolvedSpec(carrier: any): ResolvedSpec | undefined {
+  if (null == carrier || 'object' !== typeof carrier) return undefined
+  return carrier.state?.apidef?.resolved ??
+    carrier.ctx?.state?.apidef?.resolved ??
+    carrier.apidef?.resolved ??
+    undefined
+}
+
+
+export type {
+  OperationFacts,
+  ResolvedSpec,
+}
+
+export {
+  METHODS,
+  operationFacts,
+  operationIndex,
+  makeResolved,
+  publishResolved,
+  resolvedSpec,
+}

package/src/resolver.ts

@@ -15,8 +15,6 @@ async function resolveElements(
 
   const { log, model, guide } = ctx
 
-  // TODO: model access should be via a utility that generates
-  // useful errors when the target is missing
   const control = guide.control[kind][subkind]
 
   const target = kind + '.' + subkind

package/src/transform/args.ts

@@ -65,9 +65,9 @@ const argsTransform: Transform = async function(
         }
         else {
           const pathdef: PathDef = def.paths[mpoint.orig]
-          argdefs.push(...(pathdef.parameters ?? []))
+          argdefs.push(...((pathdef as any)?.parameters ?? []))
 
-          const opdef: MethodDef = (pathdef as any)[mpoint.method.toLowerCase()]
+          const opdef: MethodDef = (pathdef as any)?.[mpoint.method.toLowerCase()]
           argdefs.push(...(opdef?.parameters ?? []))
         }
 
@@ -91,14 +91,6 @@ function graphqlFieldDef(def: any, mpoint: ModelPoint): any {
 }
 
 
-// Map a GraphQL named type onto the JSON-schema-ish scalar names the
-// existing arg/field typing understands.
-//
-// Only the built-in scalars have a known JSON shape. A custom scalar can be
-// anything — JSON/JSONObject accept objects and arrays, DateTime is a
-// string, Upload is a file handle — so anything unrecognised stays
-// unconstrained rather than being wrongly advertised (and validated) as a
-// string. ID and String are the two custom-free string cases.
 function gqlScalarType(typeName: string): string | undefined {
   return 'Int' === typeName ? 'integer' :
     'Float' === typeName ? 'number' :
@@ -123,17 +115,9 @@ function resolveArgs(
   const touchedKeys = new Set<string>()
 
   each(argdefs, (argdef: ParameterDef) => {
-    // Spec name as written (e.g. `dataType`) is what the rename map is keyed
-    // 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?.({
@@ -185,13 +169,6 @@ function resolveArgs(
 }
 
 
-// OpenAPI lets specs advertise example values four ways:
-//   parameter.example          (single value, OAS 3.0+)
-//   parameter.examples          (named-example object, take first .value)
-//   parameter.schema.example   (single value on the schema)
-//   parameter.schema.default   (default value)
-// Pick the first one we find so test generators can produce valid live
-// requests even when the parameter is required and has no other source.
 function resolveArgExample(argdef: any): any {
   if (undefined !== argdef?.example) return argdef.example
 

package/src/transform/casecollide.ts

@@ -0,0 +1,80 @@
+import { each, camelify } from 'jostraca'
+
+import type { TransformResult, Transform } from '../transform'
+
+import { KIT } from '../types'
+import type { KitModel } from '../types'
+
+
+// See docs/design/derived-names.md
+function deepempty(v: any): boolean {
+  if (null == v) return true
+  if ('object' !== typeof v) return false
+  const keys = Object.keys(v)
+  if (0 === keys.length) return true
+  return keys.every((k) => deepempty(v[k]))
+}
+
+
+const casecollideTransform: Transform = async function(
+  ctx: any,
+): Promise<TransformResult> {
+  const { apimodel, guide } = ctx
+  const kit: KitModel = apimodel.main[KIT]
+
+  const bylower: { [lower: string]: string[] } = {}
+  each(kit.entity, (_entity: any, entname: string) => {
+    const lower = String(camelify(entname)).toLowerCase()
+    bylower[lower] = bylower[lower] || []
+    bylower[lower].push(entname)
+  })
+
+  const dropped: string[] = []
+
+  for (const lower of Object.keys(bylower)) {
+    const group = bylower[lower].sort()
+    if (group.length < 2) continue
+
+    // See docs/design/derived-names.md
+    const opcount = (name: string) => {
+      const ops = (kit.entity as any)[name]?.op || {}
+      return Object.keys(ops).filter((opname) => !deepempty(ops[opname])).length
+    }
+
+    const withops = group.filter(n => 0 < opcount(n))
+    const noops = group.filter(n => 0 === opcount(n))
+
+    if (0 === withops.length || 0 === noops.length) {
+      ctx.log.warn({
+        point: 'entity-case-collision',
+        entity: group,
+        note: 'entity names differ only by case and all carry operations: ' +
+          group.join(', ') + ' — the generated files collide on a ' +
+          'case-insensitive filesystem. Not resolved here: dropping one ' +
+          'would remove operations from the SDK.'
+      })
+      continue
+    }
+
+    for (const name of noops) {
+      delete (kit.entity as any)[name]
+      if (guide?.entity) delete guide.entity[name]
+      dropped.push(name)
+      ctx.log.info({
+        point: 'entity-case-collision-drop',
+        entity: name,
+        kept: withops,
+        note: 'dropped entity ' + name + ': it carries no operations and its ' +
+          'name differs only by case from ' + withops.join(', ') +
+          ', so both would generate to one file.'
+      })
+    }
+  }
+
+  return { ok: true, msg: 0 === dropped.length ? '' : 'dropped: ' + dropped.join(',') }
+}
+
+
+export {
+  casecollideTransform
+}

package/src/transform/contract.ts

@@ -1,21 +1,36 @@
-// Lossless point facts. JSON protects explicit empty contracts and schema
-// keywords from aontu unification and the model's empty-node cleanup.
+// Point contracts. See docs/design/resolved-spec-capability.md
 import type { Transform } from '../transform'
 
+import { operationFacts } from '../resolved'
+
+
 export function contractJSON(value: any): string {
-  const ancestors = new Map<any, string>()
-  function copy(v: any, path: string): any {
-    if (v === null || typeof v !== 'object') return v
-    if (ancestors.has(v)) return { $ref: ancestors.get(v) }
-    ancestors.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'))
+  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
     }
-    ancestors.delete(v)
-    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(copy(value, '#'))
+  return JSON.stringify(out)
 }
 
 // An operation needs its argument types, including recursive input objects.
@@ -44,24 +59,11 @@ export const contractTransform: Transform = async (ctx: any) => {
         const method = path?.[point.method.toLowerCase()]
         const graphql = def.query?.[point.orig] || def.mutation?.[point.orig]
         if (!method && !graphql) continue
-        const facts: any = { protocol: graphql ? 'graphql' : 'http' }
-        if (graphql) {
-          facts.field = graphql
-          facts.types = graphqlInputTypes(graphql, def.types || {})
-          facts.typesScope = 'inputs'
-          facts.invocation = point.graphql
-        } else {
-          for (const key of ['operationId', 'requestBody', 'responses', 'consumes', 'produces']) {
-            if (undefined !== method[key]) facts[key] = method[key]
-          }
-          facts.parameters = [...(path.parameters || []), ...(method.parameters || [])]
-          facts.security = method.security ?? def.security
-          facts.securitySource = method.security !== undefined ? 'operation' :
-            def.security !== undefined ? 'definition' : 'unspecified'
-          facts.securitySchemes = def.components?.securitySchemes ?? def.securityDefinitions
-          facts.consumes ??= def.consumes
-          facts.produces ??= def.produces
-        }
+        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 hint = guideOp?.live
         for (const key of ['requestBody', 'responses', 'parameters', 'security']) {
@@ -70,10 +72,18 @@ export const contractTransform: Transform = async (ctx: any) => {
             ;(facts.factSources ??= {})[key] = 'guide'
           }
         }
-        if (hint !== undefined) facts.live = hint
+        if (hint !== undefined) {
+          facts.live = hint
+          point.live = hint
+        }
+        // Identity only; facts come from the capability. See
+        // docs/design/resolved-spec-capability.md
         point.contract = { version: 1, id: point.method + ' ' + point.orig,
-          source: graphql ? 'graphql' : def.swagger ? 'swagger2' : 'openapi3',
-          json: contractJSON(facts) }
+          source: graphql ? 'graphql' : def.swagger ? 'swagger2' : 'openapi3' }
+
+        if (ctx.opts?.contractJson) {
+          point.contract.json = contractJSON(facts)
+        }
       }
     }
   }