@voxgig/apidef 2.4.1 → 3.1.0

package/src/model.ts

@@ -0,0 +1,143 @@
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
+
+// Consolidated model types for the API model derived from OpenAPI specifications
+
+import type { MethodName } from './types'
+
+
+// Operation names available on entities
+type OpName = 'load' | 'list' | 'create' | 'update' | 'remove' | 'patch' | 'head' | 'options'
+
+
+type Model = {
+  main: {
+    kit: {
+      entity: Record<string, ModelEntity>
+    }
+  }
+}
+
+
+// Entity relationships information
+type ModelEntityRelations = {
+  ancestors: string[][]
+}
+
+
+// Map of operations available on an entity
+type ModelOpMap = Partial<Record<OpName, ModelOp | undefined>>
+
+
+// Field-specific operation configuration
+type ModelFieldOp = {
+  type: any // @voxgig/struct validation schema
+  req: boolean
+}
+
+
+// Entity field definition
+type ModelField = {
+  name: string
+  type: any // @voxgig/struct validation schema
+  req: boolean
+  op: Partial<Record<OpName, ModelFieldOp>>
+}
+
+
+// Operation argument/parameter definition
+type ModelArg = {
+  name: string
+  orig: string
+  type: any // @voxgig/struct validation schema
+  kind: 'param' | 'query' | 'header' | 'cookie'
+  reqd: boolean
+}
+
+
+// Alternative implementation of an operation
+type ModelAlt = {
+  orig: string
+  method: MethodName
+  parts: string[]
+  rename: Partial<{
+    param: Record<string, string>
+    query: Record<string, string>
+    header: Record<string, string>
+    cookie: Record<string, string>
+  }>
+  args: Partial<{
+    param: ModelArg[]
+    query: ModelArg[]
+    header: ModelArg[]
+    cookie: ModelArg[]
+  }>
+  transform: {
+    req?: any
+    res?: any
+  }
+  select: {
+    exist: string[]
+    $action?: string
+  }
+}
+
+
+// Operation definition
+type ModelOp = {
+  name: OpName
+  alts: ModelAlt[]
+}
+
+
+// Entity definition - core model entity with operations and fields
+type ModelEntity = {
+  name: string,
+  op: ModelOpMap,
+  fields: ModelField[],
+  id: {
+    name: string,
+    field: string,
+  },
+  relations: ModelEntityRelations
+}
+
+
+type ModelEntityFlow = {
+  name: string,
+  entity: string
+  kind: string
+  // args: Record<string, string>
+  step: ModelEntityFlowStep[]
+}
+
+
+type ModelEntityFlowStep = {
+  op: OpName
+  input: Record<string, any>
+  match: Record<string, any>
+  data: Record<string, any>
+  spec: {
+    apply: string
+    def: Record<string, any>
+  }[]
+  valid: {
+    apply: string
+    def: Record<string, any>
+  }[]
+}
+
+
+export type {
+  OpName,
+  Model,
+  ModelEntityRelations,
+  ModelOpMap,
+  ModelFieldOp,
+  ModelField,
+  ModelArg,
+  ModelAlt,
+  ModelOp,
+  ModelEntity,
+  ModelEntityFlow,
+  ModelEntityFlowStep,
+}

package/src/parse.ts

@@ -1,20 +1,44 @@
-/* Copyright (c) 2024 Voxgig, MIT License */
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
 
 import { bundleFromString, createConfig } from '@redocly/openapi-core'
 
-import { each, snakify } from 'jostraca'
+import decircular from 'decircular'
 
+import { relativizePath } from './utility'
 
-import { depluralize } from './utility'
 
 
 // Parse an API definition source into a JSON sructure.
-async function parse(kind: string, source: any, meta?: any) {
+async function parse(kind: string, source: any, meta: { file: string }) {
   if ('OpenAPI' === kind) {
-    return parseOpenAPI(source, meta)
+
+    validateSource(kind, source, meta)
+
+    try {
+      const def = await parseOpenAPI(source, meta)
+      return def
+    }
+    catch (pe: any) {
+      if (pe.originalError) {
+        pe.originalError.message =
+          `@voxgig/apidef: parse: syntax: ${pe.originalError.message}` +
+          ` (${relativizePath(meta.file)})`
+        pe = pe.originalError
+      }
+      else {
+        pe.message =
+          `@voxgig/apidef: parse: internal: ${pe.message}` +
+          ` (${relativizePath(meta.file)})`
+      }
+
+      throw pe
+    }
   }
   else {
-    throw new Error('@voxgig/apidef-parse: unknown kind: ' + kind)
+    throw new Error(
+      `@voxgig/apidef: parse: unknown kind: ${kind}` +
+      ` (${relativizePath(meta.file)})`
+    )
   }
 }
 
@@ -59,80 +83,47 @@ async function parseOpenAPI(source: any, meta?: any) {
   addXRefs(bundleWithRefs.bundle.parsed)
 
   // Serialize back to string with x-refs preserved
-  const sourceWithXRefs = JSON.stringify(bundleWithRefs.bundle.parsed)
+  const sourceWithXRefs = JSON.stringify(decircular(bundleWithRefs.bundle.parsed))
 
   // Second pass: parse with dereferencing
   const bundle = await bundleFromString({
     source: sourceWithXRefs,
+    // source,
     config,
     dereference: true,
   })
 
-  const def = bundle.bundle.parsed
+  const def = decircular(bundle.bundle.parsed)
 
   return def
 }
 
 
 
+function validateSource(kind: string, source: any, meta: { file: string }) {
+  if (typeof source !== 'string') {
+    throw new Error(
+      `@voxgig/apidef: parse: ${kind}: source must be a string` +
+      ` (${relativizePath(meta.file)})`
+    )
+  }
 
+  // Remove YAML comment lines (lines that start with # after
+  // optional whitespace)
+  const withoutComments = source.replace(/^\s*#.*$/gm, '')
 
+  if (withoutComments.trim().length === 0) {
+    throw new Error(
+      `@voxgig/apidef: parse: ${kind}: source is empty` +
+      ` (${relativizePath(meta.file)})`
+    )
+  }
+}
 
 
-// Make consistent changes to support semantic entities.
-function rewrite(def: any) {
-  const paths = def.paths
-  each(paths, (path) => {
-    each(path.parameters, (param: any) => {
-
-      let new_param = param.name
-      let new_path = path.key$
-
-      // Rename param if nane is "id", and not the final param.
-      // Rewrite /foo/{id}/bar as /foo/{foo_id}/bar.
-      // Avoids ambiguity with bar id.
-      if (param.name.match(/^id$/i)) {
-        let m = path.key$.match(/\/([^\/]+)\/{id\}\/[^\/]/)
-
-        if (m) {
-          const parent = depluralize(snakify(m[1]))
-          new_param = `${parent}_id`
-          new_path = path.key$.replace('{id}', '{' + new_param + '}')
-        }
-      }
-      else {
-        new_param = depluralize(snakify(param.name))
-        new_path = path.key$.replace('{' + param.name + '}', '{' + new_param + '}')
-      }
-
-      let pathdef = paths[path.key$]
-      delete paths[path.key$]
-
-      paths[new_path] = pathdef
-      path.key$ = new_path
-
-      param.name = new_param
-    })
-  })
-
-
-  sortkeys(def, 'paths')
-  sortkeys(def, 'components')
-
-  return def
-}
 
 
-function sortkeys(obj: any, prop: string) {
-  const sorted: any = {}
-  const sorted_keys = Object.keys(obj[prop]).sort()
-  for (let sk of sorted_keys) {
-    sorted[sk] = obj[prop][sk]
-  }
-  obj[prop] = sorted
-}
 
 export {
   parse,
-  rewrite,
 }

package/src/resolver.ts

@@ -3,6 +3,8 @@
 
 import Path from 'node:path'
 
+import { relativizePath } from './utility'
+
 
 async function resolveElements(
   ctx: any,
@@ -77,7 +79,7 @@ async function resolveElement(
   }
   catch (e: any) {
     const err = new Error('Custom element not found: ' +
-      customtpath + ': ' + e.message)
+      relativizePath(customtpath) + ': ' + e.message)
     log.error({ what: 'element', element: target + ': ' + en, fail: 'require', err })
     throw err
   }

package/src/schematron.ts.off

@@ -0,0 +1,317 @@
+type JSONSchema = Record<string, any>;
+
+type ConvertOptions = {
+  /** Where to resolve $ref from. Use your OpenAPI doc’s components.schemas, or JSON Schema $defs. */
+  refRoots?: Array<Record<string, JSONSchema>>;
+  /** Optional: pass the entire root doc; only used if your $ref are absolute like #/components/schemas/X */
+  rootDoc?: Record<string, any>;
+};
+
+const TYPE_TOKEN: Record<string, string> = {
+  string: "$STRING",
+  number: "$NUMBER",
+  integer: "$INTEGER",
+  boolean: "$BOOLEAN",
+  null: "$NULL",
+};
+
+export function convert(
+  schema: JSONSchema | undefined,
+  opts: ConvertOptions = {}
+): any {
+  const seen = new Set<object>();
+  const resolvingRefs = new Set<string>();
+
+
+  const resolveRef = ($ref: string): JSONSchema | undefined => {
+    if (!$ref.startsWith("#/")) return undefined; // non-local refs not supported per spec; return undefined to fallback
+    const parts = $ref.slice(2).split("/").map(unescapeRefToken);
+    let node: any = opts.rootDoc ?? {};
+    for (const p of parts) node = node?.[p];
+    if (node) return node;
+
+    // Try common roots passed in refRoots (e.g., components.schemas, $defs)
+    for (const root of opts.refRoots ?? []) {
+      let probe: any = root;
+      for (const p of parts) probe = probe?.[p];
+      if (probe) return probe;
+    }
+    return undefined;
+  };
+
+  const expandRef = (sch: JSONSchema): JSONSchema => {
+    if (typeof sch?.$ref === "string") {
+      const target = resolveRef(sch.$ref);
+      if (target) return target;
+      // Not supported → per rule 10, “just expand the reference”; if we cannot, fall back to ANY.
+      return {};
+    }
+    return sch;
+  };
+
+  function convert(s: JSONSchema | undefined): any {
+    if (!s || Object.keys(s).length === 0) {
+      // Rule 13 – empty schema accepts anything
+      return "$ANY";
+    }
+
+    // Prevent cycles from blowing the stack on malformed docs
+    if (seen.has(s)) return "$ANY";
+    seen.add(s);
+
+    // // // Expand $ref immediately (Rule 10)
+    // // if (s.$ref) {
+    // //   const tgt = expandRef(s);
+    // //   // Merge local decorations on top of the ref target (common in OAS)
+    // //   const merged = { ...tgt, ...without(s, ["$ref"]) };
+    // //   const out = convert(merged);
+    // //   seen.delete(s);
+    // //   return out;
+    // // }
+
+
+    // // Expand $ref immediately (Rule 10)
+    // if (s.$ref) {
+    //   const target = expandRef(s);
+    //   const localDecor = without(s, ["$ref"]); // local fields that decorate the ref
+    //   // Use the same semantics as allOf merging to deep-merge properties/openness/etc.
+    //   const merged = mergeAllOf([target, localDecor]);
+    //   const out = convert(merged);
+    //   seen.delete(s);
+    //   return out;
+    // }
+
+    if (s.$ref) {
+      const ref = String(s.$ref);
+      if (resolvingRefs.has(ref)) {
+        // cycle detected -> cannot expand, fall back to ANY
+        seen.delete(s);
+        return "$ANY";
+      }
+      resolvingRefs.add(ref);
+
+      const target = expandRef(s); // returns referenced schema or {}
+      const localDecor = without(s, ["$ref"]);
+      // merge like allOf so local decorations augment target
+      const merged = mergeAllOf([target, localDecor]);
+
+      const out = convert(merged);
+
+      resolvingRefs.delete(ref);
+      seen.delete(s);
+      return out;
+    }
+
+
+    // Composition
+    if (Array.isArray(s.allOf) && s.allOf.length > 0) {
+      const merged = mergeAllOf(s.allOf.map((x) => expandRef(x)));
+      // Carry over top-level decorations (e.g., nullable, annotations)
+      const mergedWithTop = { ...merged, ...without(s, ["allOf"]) };
+      const out = convert(mergedWithTop);
+      seen.delete(s);
+      return out;
+    }
+
+    if (Array.isArray(s.oneOf) && s.oneOf.length > 0) {
+      const alts = s.oneOf.map((x) => convert(expandRef(x)));
+      const out = ["$ONE", ...alts];
+      seen.delete(s);
+      return out;
+    }
+
+    if (Array.isArray(s.anyOf) && s.anyOf.length > 0) {
+      const alts = s.anyOf.map((x) => convert(expandRef(x)));
+      const out = ["$ANY", ...alts]; // Rule 3 – anyOf uses "$ANY" in the same directive position
+      seen.delete(s);
+      return out;
+    }
+
+    // Enum / const → $EXACT
+    if (Array.isArray(s.enum) && s.enum.length > 0) {
+      const out = ["$EXACT", ...s.enum];
+      seen.delete(s);
+      return out;
+    }
+    if (Object.prototype.hasOwnProperty.call(s, "const")) {
+      const out = ["$EXACT", s.const];
+      seen.delete(s);
+      return out;
+    }
+
+    // Handle OpenAPI nullable at this level by wrapping the base type later
+    const nullable = s.nullable === true;
+
+    // Type handling (could be string or array)
+    const t = s.type;
+    if (Array.isArray(t) && t.length > 0) {
+      // Union of primitives (and possibly null)
+      const tokens = t.map((tt) => TYPE_TOKEN[tt] ?? "$ANY");
+      const out = ["$ONE", ...tokens];
+      seen.delete(s);
+      return out;
+    }
+
+    // Objects
+    if (t === "object" || s.properties || s.additionalProperties !== undefined) {
+      const obj: Record<string, any> = {};
+
+      // $OPEN
+      if (s.additionalProperties === true) {
+        obj["$OPEN"] = true;
+      } else if (s.additionalProperties && typeof s.additionalProperties === "object") {
+        // We cannot express typed extras (Rule 6). Keep it open but untyped.
+        obj["$OPEN"] = true;
+      }
+      // $NOTE annotations (Rule 11)
+      const note: Record<string, any> = {};
+      if (s.readOnly === true) note.readOnly = true;
+      if (s.writeOnly === true) note.writeOnly = true;
+      if (s.deprecated === true) note.deprecated = true;
+      if (Object.keys(note).length > 0) obj["$NOTE"] = note;
+
+      const props = s.properties ?? {};
+      for (const [key, sub] of Object.entries<JSONSchema>(props)) {
+        const converted = convert(expandRef(sub));
+        const isNullable =
+          sub?.nullable === true ||
+          (Array.isArray(sub?.type) && sub.type.includes("null")) ||
+          includesNullViaOneAnyOf(sub);
+
+        obj[key] = isNullable ? wrapNullable(converted) : converted;
+      }
+
+      seen.delete(s);
+      return obj;
+    }
+
+    // Arrays
+    if (t === "array" || s.items) {
+      const items = s.items;
+      if (Array.isArray(items)) {
+        // Tuple validation → positional sub-schemas
+        const out = items.map((it) => convert(expandRef(it)));
+        seen.delete(s);
+        return out;
+      } else if (items && typeof items === "object") {
+        // Homogeneous array → ["$CHILD", sub]
+        const out = ["$CHILD", convert(expandRef(items))];
+        seen.delete(s);
+        return out;
+      } else {
+        // No items → accept any child element
+        seen.delete(s);
+        return [];
+      }
+    }
+
+    // Primitives
+    if (typeof t === "string" && TYPE_TOKEN[t]) {
+      const token = TYPE_TOKEN[t];
+      const base = token;
+
+      const out = nullable ? wrapNullable(base) : base;
+      seen.delete(s);
+      return out;
+    }
+
+    // No explicit type, but we might still infer:
+    if (s.properties || s.additionalProperties !== undefined) {
+      // already handled in object branch, but keep a guard
+      const out = convert({ ...s, type: "object" });
+      seen.delete(s);
+      return out;
+    }
+    if (s.items) {
+      const out = convert({ ...s, type: "array" });
+      seen.delete(s);
+      return out;
+    }
+
+    // Fallback
+    seen.delete(s);
+    return "$ANY";
+  }
+
+  const result = convert(schema);
+  return result;
+}
+
+/* -------------------------- helpers -------------------------- */
+
+function unescapeRefToken(s: string) {
+  // JSON Pointer ~0 -> ~, ~1 -> /
+  return s.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function without<T extends Record<string, any>>(obj: T, keys: string[]): T {
+  const copy: any = {};
+  for (const k of Object.keys(obj)) if (!keys.includes(k)) copy[k] = obj[k];
+  return copy;
+}
+
+function includesNullViaOneAnyOf(s: JSONSchema): boolean {
+  const hasNullIn = (arr?: any[]) =>
+    Array.isArray(arr) &&
+    arr.some((x) => x?.type === "null" || (Array.isArray(x?.type) && x.type.includes("null")));
+  return hasNullIn(s.oneOf) || hasNullIn(s.anyOf);
+}
+
+function wrapNullable(inner: any) {
+  // Rule 1/4 – nullable → ["$ONE", inner, "$NULL"]
+  return Array.isArray(inner) && inner[0] === "$ONE"
+    ? inner.includes("$NULL")
+      ? inner
+      : ["$ONE", ...inner.slice(1), "$NULL"]
+    : ["$ONE", inner, "$NULL"];
+}
+
+function mergeAllOf(schemas: JSONSchema[]): JSONSchema {
+  const out: JSONSchema = {};
+  let anyObject = false;
+
+  for (const s of schemas) {
+    const schema = s || {};
+
+    if (schema.type === "object" || schema.properties || schema.additionalProperties !== undefined) {
+      anyObject = true;
+      out.type = "object";
+
+      // --- properties: merge without losing earlier branches ---
+      const srcProps = schema.properties ?? {};
+      const dstProps = (out.properties = out.properties ?? {});
+      for (const [k, v] of Object.entries(srcProps)) {
+        if (k in dstProps) {
+          // Combine the two property schemas using allOf semantics.
+          // This preserves earlier constraints like {type:'number'} and
+          // later decorations like {nullable:true}.
+          dstProps[k] = { allOf: [dstProps[k], v] };
+        } else {
+          dstProps[k] = v;
+        }
+      }
+
+      // --- additionalProperties: openness is "true if any true/object" ---
+      const ap = schema.additionalProperties;
+      if (ap === true || (ap && typeof ap === "object")) {
+        out.additionalProperties = true;
+      } else if (out.additionalProperties === undefined) {
+        out.additionalProperties = ap;
+      }
+
+      // --- required: union (not used in voxgig/struct but harmless to keep) ---
+      if (Array.isArray(schema.required)) {
+        const req = new Set([...(out.required ?? []), ...schema.required]);
+        out.required = Array.from(req);
+      }
+    } else {
+      // For non-object shapes in allOf, a shallow merge is the best we can do.
+      Object.assign(out, schema);
+    }
+  }
+
+  // If nothing was objecty, return a shallow merge across all schemas.
+  return anyObject
+    ? out
+    : (schemas.reduce((a, b) => ({ ...a, ...(b || {}) }), {}) as JSONSchema);
+}