@api-client/core 0.18.15 → 0.18.17

package/src/modeling/DomainSerialization.ts

@@ -1,6 +1,15 @@
 import type { JsonEdge, Node } from '@api-client/graph/graph/types.js'
 import { Graph } from '@api-client/graph/graph/Graph.js'
-import type { DataDomainGraph, DomainGraphEdge, DomainGraphNodeType, SerializedGraph } from './types.js'
+import type {
+  DataDomainGraph,
+  DomainGraphEdge,
+  DomainGraphNodeType,
+  SerializedGraph,
+  DeserializationMode,
+  DeserializationResult,
+  DeserializationIssue,
+  DeserializeOptions,
+} from './types.js'
 import {
   DomainAssociationKind,
   DomainEntityKind,
@@ -78,7 +87,154 @@ function writeEdges(g: DataDomainGraph, domainKey: string): JsonEdge<DomainGraph
   return result
 }
 
+/**
+ * Validates the graph consistency before serialization.
+ * Ensures that all required edges exist for properties and associations.
+ * @param g The graph to validate
+ * @param domainKey The domain key to validate
+ * @throws Error if the graph is inconsistent
+ */
+function validateGraphConsistency(g: DataDomainGraph, domainKey: string): void {
+  const validationErrors: string[] = []
+
+  // Get all nodes that belong to this domain
+  const domainNodes = new Set<string>()
+  for (const nodeId of g.nodes()) {
+    const node = g.node(nodeId)
+    if (node && node.domain.key === domainKey) {
+      domainNodes.add(nodeId)
+    }
+  }
+
+  // Validate that properties and associations have parent edges
+  for (const nodeId of domainNodes) {
+    const node = g.node(nodeId)
+    if (!node) continue
+
+    if (node.kind === DomainPropertyKind || node.kind === DomainAssociationKind) {
+      // These nodes must have exactly one incoming edge from their parent entity
+      const incomingEdges = [...g.inEdges(nodeId)]
+      const parentEdges = incomingEdges.filter((edge) => {
+        const sourceNode = g.node(edge.v)
+        return sourceNode && sourceNode.domain.key === domainKey
+      })
+
+      if (parentEdges.length === 0) {
+        const nodeType = node.kind === DomainPropertyKind ? 'Property' : 'Association'
+        validationErrors.push(
+          `${nodeType} "${node.info.name}" (${nodeId}) has no parent entity edge. ` +
+            `This will cause deserialization to fail.`
+        )
+      } else if (parentEdges.length > 1) {
+        const nodeType = node.kind === DomainPropertyKind ? 'Property' : 'Association'
+        const parentIds = parentEdges.map((e) => e.v).join(', ')
+        validationErrors.push(
+          `${nodeType} "${node.info.name}" (${nodeId}) has multiple parent edges: ${parentIds}. ` +
+            `This may cause deserialization issues.`
+        )
+      } else {
+        // Validate that the parent is actually an entity
+        const parentEdge = parentEdges[0]
+        const parentNode = g.node(parentEdge.v)
+        if (!parentNode || parentNode.kind !== DomainEntityKind) {
+          const nodeType = node.kind === DomainPropertyKind ? 'Property' : 'Association'
+          validationErrors.push(
+            `${nodeType} "${node.info.name}" (${nodeId}) has a parent that is not an entity. ` +
+              `Parent: ${parentNode?.kind || 'unknown'} (${parentEdge.v})`
+          )
+        }
+      }
+    }
+
+    // Validate that entities have model parents
+    if (node.kind === DomainEntityKind) {
+      const parents = [...g.parents(nodeId)]
+      const hasModelParent = parents.some((parentId) => {
+        const parent = g.node(parentId)
+        return parent && parent.kind === DomainModelKind
+      })
+
+      if (!hasModelParent) {
+        validationErrors.push(
+          `Entity "${node.info.name}" (${nodeId}) has no model parent. ` + `Entities must belong to a model.`
+        )
+      }
+    }
+
+    // Validate that models have either namespace parents or are at root level
+    if (node.kind === DomainModelKind) {
+      const parents = [...g.parents(nodeId)]
+      const hasNamespaceParent = parents.some((parentId) => {
+        const parent = g.node(parentId)
+        return parent && parent.kind === DomainNamespaceKind
+      })
+
+      // Models can either be at root level (no parents) or have a namespace parent
+      // They should not have other types of parents
+      if (parents.length > 0 && !hasNamespaceParent) {
+        const invalidParents = parents
+          .map((parentId) => {
+            const parent = g.node(parentId)
+            return `${parent?.kind || 'unknown'} (${parentId})`
+          })
+          .join(', ')
+        validationErrors.push(
+          `Model "${node.info.name}" (${nodeId}) has invalid parent types: ${invalidParents}. ` +
+            `Models can only belong to namespaces or be at root level.`
+        )
+      }
+    }
+  }
+
+  // Validate association targets exist
+  for (const nodeId of domainNodes) {
+    const node = g.node(nodeId)
+    if (node && node.kind === DomainAssociationKind) {
+      const association = node as DomainAssociation
+      const outgoingEdges = [...g.outEdges(nodeId)]
+
+      // Check that association has target edges
+      const targetEdges = outgoingEdges.filter((edge) => {
+        const edgeData = g.edge(edge)
+        return edgeData && edgeData.type === 'association'
+      })
+
+      if (targetEdges.length === 0) {
+        validationErrors.push(
+          `Association "${association.info.name}" (${nodeId}) has no target entities. ` +
+            `Associations must reference at least one target entity.`
+        )
+      }
+
+      // Validate that all target entities exist
+      for (const targetEdge of targetEdges) {
+        const targetNode = g.node(targetEdge.w)
+        if (!targetNode) {
+          validationErrors.push(
+            `Association "${association.info.name}" (${nodeId}) references non-existent target: ${targetEdge.w}`
+          )
+        } else if (targetNode.kind !== DomainEntityKind) {
+          validationErrors.push(
+            `Association "${association.info.name}" (${nodeId}) references non-entity target: ` +
+              `${targetNode.kind} (${targetEdge.w})`
+          )
+        }
+      }
+    }
+  }
+
+  if (validationErrors.length > 0) {
+    throw new Error(
+      `Graph consistency validation failed for domain "${domainKey}":\n` +
+        validationErrors.map((error) => `  - ${error}`).join('\n')
+    )
+  }
+}
+
 export function serialize(g: DataDomainGraph, domainKey: string): SerializedGraph {
+  // Validate graph consistency before serialization
+  validateGraphConsistency(g, domainKey)
+
   const json: SerializedGraph = {
     options: {
       directed: g.isDirected(),
@@ -198,43 +354,124 @@ function findEdgeParent(child: string, edges: JsonEdge<DomainGraphEdge>[]): stri
  * @param root The DataDomain instance to use as the root for the graph
  * @param entry The node entry to restore
  * @param edges The list of serialized graph edges
- * @returns The restored node instance
- * @throws Error if the entry is malformed or the kind is unknown
+ * @param mode The deserialization mode
+ * @param issues Array to collect issues in lenient mode
+ * @returns The restored node instance or undefined if failed in lenient mode
+ * @throws Error if the entry is malformed or the kind is unknown in strict mode
  */
-function prepareNode(root: DataDomain, entry: unknown, edges: JsonEdge<DomainGraphEdge>[]): DomainGraphNodeType {
+function prepareNode(
+  root: DataDomain,
+  entry: unknown,
+  edges: JsonEdge<DomainGraphEdge>[],
+  mode: DeserializationMode,
+  issues: DeserializationIssue[]
+): DomainGraphNodeType | undefined {
   if (!entry) {
-    throw new Error(`Unable to restore data domain graph. Malformed node entry`)
+    const issue: DeserializationIssue = {
+      type: 'malformed_entry',
+      severity: 'error',
+      message: 'Unable to restore data domain graph. Malformed node entry',
+    }
+    issues.push(issue)
+
+    if (mode === 'strict') {
+      throw new Error(issue.message)
+    }
+    return undefined
   }
-  const domainElement = entry as { kind?: string }
+
+  const domainElement = entry as { kind?: string; key?: string }
   if (!domainElement.kind) {
-    throw new Error(`Unable to restore data domain graph. Malformed node entry`)
-  }
-  if (domainElement.kind === DomainNamespaceKind) {
-    return new DomainNamespace(root, domainElement as DomainNamespaceSchema)
-  }
-  if (domainElement.kind === DomainModelKind) {
-    return new DomainModel(root, domainElement as DomainModelSchema)
-  }
-  if (domainElement.kind === DomainEntityKind) {
-    return new DomainEntity(root, domainElement as DomainEntitySchema)
-  }
-  if (domainElement.kind === DomainPropertyKind) {
-    const typed = domainElement as DomainPropertySchema
-    const parent = findEdgeParent(typed.key, edges)
-    if (!parent) {
-      throw new Error(`Unable to restore data domain graph. Malformed node entry`)
+    const issue: DeserializationIssue = {
+      type: 'malformed_entry',
+      severity: 'error',
+      message: 'Unable to restore data domain graph. Node entry missing kind property',
+      affectedKey: domainElement.key,
     }
-    return new DomainProperty(root, parent, typed)
+    issues.push(issue)
+
+    if (mode === 'strict') {
+      throw new Error(issue.message)
+    }
+    return undefined
   }
-  if (domainElement.kind === DomainAssociationKind) {
-    const typed = domainElement as DomainAssociationSchema
-    const parent = findEdgeParent(typed.key, edges)
-    if (!parent) {
-      throw new Error(`Unable to restore data domain graph. Malformed node entry`)
+
+  try {
+    if (domainElement.kind === DomainNamespaceKind) {
+      return new DomainNamespace(root, domainElement as DomainNamespaceSchema)
+    }
+    if (domainElement.kind === DomainModelKind) {
+      return new DomainModel(root, domainElement as DomainModelSchema)
+    }
+    if (domainElement.kind === DomainEntityKind) {
+      return new DomainEntity(root, domainElement as DomainEntitySchema)
+    }
+    if (domainElement.kind === DomainPropertyKind) {
+      const typed = domainElement as DomainPropertySchema
+      const parent = findEdgeParent(typed.key, edges)
+      if (!parent) {
+        const issue: DeserializationIssue = {
+          type: 'missing_edge',
+          severity: 'error',
+          message: `Property "${typed.info?.name || typed.key}" has no parent entity edge`,
+          affectedKey: typed.key,
+          resolution: mode === 'lenient' ? 'Property will be skipped' : undefined,
+        }
+        issues.push(issue)
+
+        if (mode === 'strict') {
+          throw new Error(`Unable to restore data domain graph. Malformed node entry`)
+        }
+        return undefined
+      }
+      return new DomainProperty(root, parent, typed)
+    }
+    if (domainElement.kind === DomainAssociationKind) {
+      const typed = domainElement as DomainAssociationSchema
+      const parent = findEdgeParent(typed.key, edges)
+      if (!parent) {
+        const issue: DeserializationIssue = {
+          type: 'missing_edge',
+          severity: 'error',
+          message: `Association "${typed.info?.name || typed.key}" has no parent entity edge`,
+          affectedKey: typed.key,
+          resolution: mode === 'lenient' ? 'Association will be skipped' : undefined,
+        }
+        issues.push(issue)
+        if (mode === 'strict') {
+          throw new Error(`Unable to restore data domain graph. Malformed node entry`)
+        }
+        return undefined
+      }
+      return new DomainAssociation(root, parent, typed)
+    }
+
+    const issue: DeserializationIssue = {
+      type: 'unknown_kind',
+      severity: 'error',
+      message: `Unknown node kind: ${domainElement.kind}`,
+      affectedKey: domainElement.key,
     }
-    return new DomainAssociation(root, parent, typed)
+    issues.push(issue)
+
+    if (mode === 'strict') {
+      throw new Error(`Unable to restore data domain graph. Unknown node kind ${domainElement.kind}`)
+    }
+    return undefined
+  } catch (error) {
+    const issue: DeserializationIssue = {
+      type: 'malformed_entry',
+      severity: 'error',
+      message: `Failed to create node: ${error instanceof Error ? error.message : String(error)}`,
+      affectedKey: domainElement.key,
+    }
+    issues.push(issue)
+
+    if (mode === 'strict') {
+      throw error
+    }
+    return undefined
   }
-  throw new Error(`Unable to restore data domain graph. Unknown node kind ${domainElement.kind}`)
 }
 
 /**
@@ -246,74 +483,223 @@ function prepareNode(root: DataDomain, entry: unknown, edges: JsonEdge<DomainGra
  *
  * @param root The DataDomain instance to use as the root for the graph
  * @param json The previously serialized graph
- * @returns Deserialized graph instance
+ * @param dependencies An array of foreign data domains to register with this domain
+ * @param mode The deserialization mode - 'strict' throws errors, 'lenient' collects issues
+ * @returns DeserializationResult with graph, issues, and success status
+ * @throws Error in strict mode when any issue is encountered
  */
-export function deserialize(root: DataDomain, json?: SerializedGraph, dependencies?: DataDomain[]): DataDomainGraph {
+export function deserialize(root: DataDomain, options: DeserializeOptions = {}): DeserializationResult {
+  const { json, dependencies, mode = 'strict' } = options
   const g = new Graph<unknown, DomainGraphNodeType, DomainGraphEdge>({
     compound: true,
     multigraph: true,
     directed: true,
   })
+  const issues: DeserializationIssue[] = []
   let foreignNodes = new Set<string>()
   let foreignEdges = new Set<string>()
+
+  // Process dependencies
   if (dependencies) {
     for (const dependency of dependencies) {
-      const result = mergeGraph(g, dependency.graph, dependency.key)
-      if (result.edges.size) {
-        foreignEdges = new Set([...foreignEdges, ...result.edges])
-      }
-      if (result.nodes.size) {
-        foreignNodes = new Set([...foreignNodes, ...result.nodes])
+      try {
+        const result = mergeGraph(g, dependency.graph, dependency.key)
+        if (result.edges.size) {
+          foreignEdges = new Set([...foreignEdges, ...result.edges])
+        }
+        if (result.nodes.size) {
+          foreignNodes = new Set([...foreignNodes, ...result.nodes])
+        }
+        root.dependencies.set(dependency.key, dependency)
+      } catch (error) {
+        const message = `Failed to merge dependency "${dependency.key}": ${error instanceof Error ? error.message : String(error)}`
+
+        if (mode === 'strict') {
+          throw new Error(message)
+        }
+
+        const issue: DeserializationIssue = {
+          type: 'missing_dependency',
+          severity: 'error',
+          message,
+          affectedKey: dependency.key,
+          resolution: 'Dependency will be skipped',
+        }
+        issues.push(issue)
       }
-      root.dependencies.set(dependency.key, dependency)
     }
   }
+
   if (!json) {
-    return g
+    return {
+      graph: g,
+      issues,
+      success: true,
+    }
   }
+
+  // Process nodes
   if (Array.isArray(json.nodes)) {
     // 1st pass - set up nodes
     const parentInfo = new Map<string, string[]>()
     for (const entry of json.nodes) {
-      g.setNode(entry.v, prepareNode(root, entry.value, json.edges))
-      if (entry.parents) {
-        parentInfo.set(entry.v, entry.parents)
+      const node = prepareNode(root, entry.value, json.edges, mode, issues)
+      if (node) {
+        g.setNode(entry.v, node)
+        if (entry.parents) {
+          parentInfo.set(entry.v, entry.parents)
+        }
       }
+      // Note: prepareNode throws in strict mode, so we won't reach here if there's an error
     }
+
     // 2nd pass - set up parents
     for (const [key, parents] of parentInfo) {
-      // In data domain graph, all nodes that can have parents can only have a single parent.
-      // It's the business logic of the library.
-      // Parent-child relationships:
-      // - Namespace -> Namespace
-      // - Namespace -> Model
-      // - Model -> Entity
-      // Entities and Association are associated with the parent entity through edges.
+      // Verify the node still exists (might have been skipped in lenient mode)
+      if (!g.hasNode(key)) {
+        const issue: DeserializationIssue = {
+          type: 'missing_node',
+          severity: 'warning',
+          message: `Cannot set parents for missing node: ${key}`,
+          affectedKey: key,
+          resolution: 'Parent relationship will be skipped',
+        }
+        issues.push(issue)
+        continue
+      }
+
       for (const parent of parents) {
-        g.setParent(key, parent)
+        // Verify parent exists
+        if (!g.hasNode(parent)) {
+          const issue: DeserializationIssue = {
+            type: 'missing_node',
+            severity: 'warning',
+            message: `Parent node "${parent}" not found for child "${key}"`,
+            affectedKey: key,
+            context: { parentKey: parent },
+            resolution: 'Parent relationship will be skipped',
+          }
+          issues.push(issue)
+          continue
+        }
+
+        try {
+          g.setParent(key, parent)
+        } catch (error) {
+          const message = `Failed to set parent "${parent}" for child "${key}": ${error instanceof Error ? error.message : String(error)}`
+          const issue: DeserializationIssue = {
+            type: 'invalid_parent',
+            severity: 'warning',
+            message,
+            affectedKey: key,
+            context: { parentKey: parent },
+            resolution: 'Parent relationship will be skipped',
+          }
+          issues.push(issue)
+        }
       }
     }
   }
+
+  // Process edges
   if (Array.isArray(json.edges)) {
     for (const entry of json.edges) {
       if (!entry.value) {
-        throw new Error(`Unable to restore data domain graph. Malformed edge entry`)
+        const message = 'Edge entry missing value'
+
+        if (mode === 'strict') {
+          throw new Error(message)
+        }
+
+        const issue: DeserializationIssue = {
+          type: 'malformed_entry',
+          severity: 'error',
+          message,
+          context: { edge: entry },
+        }
+        issues.push(issue)
+        continue
       }
+
+      // Handle foreign edges
       if (entry.value.foreign) {
         // The `v` has to be local to the graph. The `w` must be foreign.
         if (!foreignNodes.has(entry.w)) {
-          // console.warn(`Missing foreign node: ${entry.w}. Skipping edge.`)
+          // Note, we don't consider this an error, just a warning.
+          // Because of that, we don't throw an error here.
+          const issue: DeserializationIssue = {
+            type: 'missing_node',
+            severity: 'warning',
+            message: `Missing foreign node: ${entry.w}`,
+            affectedKey: entry.w,
+            resolution: 'Edge will be skipped',
+          }
+          issues.push(issue)
           continue
         }
       }
+
+      // Check if nodes exist for the edge
       if (foreignNodes.has(entry.v) || foreignNodes.has(entry.w)) {
         if (!g.hasNode(entry.v) || !g.hasNode(entry.w)) {
-          // console.warn(`Missing foreign node: ${entry.v} or ${entry.w}. Skipping edge.`)
+          const issue: DeserializationIssue = {
+            type: 'missing_node',
+            severity: 'warning',
+            message: `Missing foreign node for edge: ${entry.v} -> ${entry.w}`,
+            context: { sourceNode: entry.v, targetNode: entry.w },
+            resolution: 'Edge will be skipped',
+          }
+          issues.push(issue)
+          continue
+        }
+      } else {
+        // Both nodes should be local - verify they exist
+        if (!g.hasNode(entry.v)) {
+          const issue: DeserializationIssue = {
+            type: 'missing_node',
+            severity: 'warning',
+            message: `Source node not found for edge: ${entry.v}`,
+            affectedKey: entry.v,
+            resolution: 'Edge will be skipped',
+          }
+          issues.push(issue)
+          continue
+        }
+
+        if (!g.hasNode(entry.w)) {
+          const issue: DeserializationIssue = {
+            type: 'missing_node',
+            severity: 'warning',
+            message: `Target node not found for edge: ${entry.w}`,
+            affectedKey: entry.w,
+            resolution: 'Edge will be skipped',
+          }
+          issues.push(issue)
           continue
         }
       }
-      g.setEdge({ v: entry.v, w: entry.w, name: entry.name }, entry.value)
+
+      try {
+        g.setEdge({ v: entry.v, w: entry.w, name: entry.name }, entry.value)
+      } catch (error) {
+        const message = `Failed to create edge ${entry.v} -> ${entry.w}: ${error instanceof Error ? error.message : String(error)}`
+        const issue: DeserializationIssue = {
+          type: 'malformed_entry',
+          severity: 'warning',
+          message,
+          context: { sourceNode: entry.v, targetNode: entry.w },
+          resolution: 'Edge will be skipped',
+        }
+        issues.push(issue)
+      }
     }
   }
-  return g
+
+  const hasErrors = issues.some((issue) => issue.severity === 'error')
+
+  return {
+    graph: g,
+    issues,
+    success: !hasErrors,
+  }
 }

package/src/modeling/importers/SchemaFilteringStrategy.ts

@@ -107,17 +107,9 @@ export class SchemaFilteringStrategy {
       return true
     }
 
-    // Check for schemas that only contain a single allOf with a $ref (like ActionStatusType)
-    if (
-      schema.type === 'object' &&
-      schema.allOf?.length === 1 &&
-      typeof schema.allOf[0] === 'object' &&
-      '$ref' in schema.allOf[0] &&
-      !schema.properties &&
-      !schema.additionalProperties
-    ) {
-      return true
-    }
+    // Note: We removed the check for single allOf with $ref as this represents
+    // valid schema inheritance/extension patterns (e.g., BlogPosting extending SocialMediaPosting)
+    // Such schemas should be included as they define meaningful type hierarchies
 
     // Check for schemas that only have description and type but no structure
     if (