fix(DataMapper): Support circular xs:include

Fixes: #3206

While it is invalid from XML schema perspective, there is(are) well known XML schema such as FPML having it. Support it anyway.

Author: igarashitm

packages/ui/src/services/document/xml-schema/xml-schema-analysis.service.test.ts

@@ -75,17 +75,18 @@ ${elements}
     expect(result.errors[0].filePath).toBe('A.xsd');
   });
 
-  it('should detect circular includes', () => {
+  it('should warn on circular includes instead of erroring', () => {
     const files = {
       'A.xsd': makeSchema({ includes: ['B.xsd'] }),
       'B.xsd': makeSchema({ includes: ['A.xsd'] }),
     };
     const result = XmlSchemaAnalysisService.analyze(files);
     const circularErrors = result.errors.filter((e) => e.message.includes('Circular'));
-    expect(circularErrors.length).toBeGreaterThan(0);
-    expect(circularErrors[0].message).toContain('A.xsd');
-    expect(circularErrors[0].message).toContain('B.xsd');
-    expect(circularErrors[0].filePath).toBeUndefined();
+    expect(circularErrors).toHaveLength(0);
+    const circularWarnings = result.warnings.filter((w) => w.message.includes('Circular xs:include'));
+    expect(circularWarnings.length).toBeGreaterThan(0);
+    expect(circularWarnings[0].message).toContain('A.xsd');
+    expect(circularWarnings[0].message).toContain('B.xsd');
   });
 
   it('should allow circular imports (different namespaces)', () => {

packages/ui/src/services/document/xml-schema/xml-schema-analysis.service.ts

@@ -73,10 +73,10 @@ export class XmlSchemaAnalysisService {
       }
     }
 
-    const circularErrors = XmlSchemaAnalysisService.detectCircularIncludes(fileInfos, edges);
-    errors.push(...circularErrors);
+    const circularIncludeWarnings = XmlSchemaAnalysisService.detectCircularIncludes(fileInfos, edges);
 
     const warnings = XmlSchemaAnalysisService.detectCircularImports(fileInfos, edges);
+    warnings.push(...circularIncludeWarnings);
 
     const includeNsErrors = XmlSchemaAnalysisService.validateIncludeNamespaces(fileInfos, edges);
     errors.push(...includeNsErrors);

packages/ui/src/services/document/xml-schema/xml-schema-document.service.schema-files.test.ts

@@ -6,8 +6,10 @@ import {
 } from '../../../models/datamapper/document';
 import { IFieldSubstitution } from '../../../models/datamapper/metadata';
 import { NS_XML_SCHEMA } from '../../../models/datamapper/standard-namespaces';
-import { FieldOverrideVariant } from '../../../models/datamapper/types';
+import { FieldOverrideVariant, Types } from '../../../models/datamapper/types';
 import {
+  getCircularIncludeAXsd,
+  getCircularIncludeBXsd,
   getCommonTypesXsd,
   getElementRefXsd,
   getFieldSubstitutionXsd,
@@ -273,7 +275,7 @@ describe('XmlSchemaDocumentService / schema file management', () => {
       expect(result.errors!.length).toBeGreaterThan(0);
     });
 
-    it('should return error for circular includes', () => {
+    it('should warn but succeed for circular includes', () => {
       const schemaA = `<?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:include schemaLocation="B.xsd"/>
@@ -293,10 +295,45 @@ describe('XmlSchemaDocumentService / schema file management', () => {
         { 'A.xsd': schemaA, 'B.xsd': schemaB },
       );
       const result = XmlSchemaDocumentService.createXmlSchemaDocument(definition);
-      expect(result.validationStatus).toBe('error');
-      expect(result.errors![0].message).toContain('Circular xs:include');
-      expect(result.errors).toBeDefined();
-      expect(result.errors!.length).toBeGreaterThan(0);
+      expect(result.validationStatus).toBe('warning');
+      expect(result.warnings).toBeDefined();
+      expect(result.warnings!.some((w) => w.message.includes('Circular xs:include'))).toBe(true);
+      expect(result.document).toBeDefined();
+    });
+
+    it('should resolve cross-referenced types in circular includes', () => {
+      const definition = new DocumentDefinition(
+        DocumentType.SOURCE_BODY,
+        DocumentDefinitionType.XML_SCHEMA,
+        BODY_DOCUMENT_ID,
+        {
+          'CircularIncludeA.xsd': getCircularIncludeAXsd(),
+          'CircularIncludeB.xsd': getCircularIncludeBXsd(),
+        },
+      );
+      const result = XmlSchemaDocumentService.createXmlSchemaDocument(definition);
+      expect(result.validationStatus).toBe('warning');
+      expect(result.warnings!.some((w) => w.message.includes('Circular xs:include'))).toBe(true);
+      const document = result.document as XmlSchemaDocument;
+      expect(document).toBeDefined();
+      expect(document.fields[0].name).toBe('Root');
+
+      const orderField = document.fields[0].fields.find((f) => f.name === 'order');
+      expect(orderField).toBeDefined();
+      expect(orderField!.type).toBe(Types.Container);
+
+      const NS = 'http://example.com/circular';
+      const orderTypeQName = new QName(NS, 'OrderType');
+      expect(document.xmlSchemaCollection.getTypeByQName(orderTypeQName)).toBeDefined();
+      const productTypeQName = new QName(NS, 'ProductType');
+      expect(document.xmlSchemaCollection.getTypeByQName(productTypeQName)).toBeDefined();
+
+      const orderFragment = document.namedTypeFragments[orderTypeQName.toString()];
+      expect(orderFragment).toBeDefined();
+      expect(orderFragment.fields.some((f) => f.name === 'product')).toBe(true);
+      const productFragment = document.namedTypeFragments[productTypeQName.toString()];
+      expect(productFragment).toBeDefined();
+      expect(productFragment.fields.some((f) => f.name === 'productName')).toBe(true);
     });
 
     it('should warn with circular imports (different namespaces)', () => {

packages/ui/src/services/document/xml-schema/xml-schema-document.service.ts

@@ -143,10 +143,10 @@ export class XmlSchemaDocumentService {
    */
   private static loadSchemaFiles(
     collection: XmlSchemaCollection,
-    analysis: { loadOrder: string[]; edges: Array<{ directive: { type: string }; to: string }> },
+    analysis: { loadOrder: string[]; edges: Array<{ directive: { type: string }; to: string; from: string }> },
     definitionFiles: Record<string, string>,
   ): { error?: { message: string; filePath?: string } } {
-    const includeTargets = new Set(analysis.edges.filter((e) => e.directive.type === 'include').map((e) => e.to));
+    const includeTargets = XmlSchemaDocumentService.computeIncludeTargetsToSkip(analysis.loadOrder, analysis.edges);
 
     try {
       for (const path of analysis.loadOrder) {
@@ -162,6 +162,62 @@ export class XmlSchemaDocumentService {
     }
   }
 
+  /**
+   * Determines which include-target files can safely be skipped during direct loading.
+   * Normally, files that are xs:include targets are loaded indirectly when their parent
+   * schema processes the include directive. However, with circular includes (A includes B,
+   * B includes A), all files in the cycle become include targets — skipping them all means
+   * nothing loads. This method ensures at least one file per isolated cycle is promoted to
+   * direct loading so the SchemaBuilder can process the cycle via its built-in
+   * `collection.check(key)` guard.
+   */
+  private static computeIncludeTargetsToSkip(
+    loadOrder: string[],
+    edges: Array<{ directive: { type: string }; to: string; from: string }>,
+  ): Set<string> {
+    const includeEdges = edges.filter((e) => e.directive.type === 'include');
+    const includeTargets = new Set(includeEdges.map((e) => e.to));
+    const adjacencyMap = XmlSchemaDocumentService.buildIncludeAdjacency(includeEdges);
+
+    const reachable = new Set<string>();
+    const seeds = loadOrder.filter((p) => !includeTargets.has(p));
+    XmlSchemaDocumentService.bfsReachable(seeds, adjacencyMap, reachable);
+
+    for (const path of loadOrder) {
+      if (reachable.has(path)) continue;
+      includeTargets.delete(path);
+      XmlSchemaDocumentService.bfsReachable([path], adjacencyMap, reachable);
+    }
+
+    return includeTargets;
+  }
+
+  private static buildIncludeAdjacency(includeEdges: Array<{ from: string; to: string }>): Map<string, string[]> {
+    const adjacencyMap = new Map<string, string[]>();
+    for (const edge of includeEdges) {
+      const list = adjacencyMap.get(edge.from) ?? [];
+      list.push(edge.to);
+      adjacencyMap.set(edge.from, list);
+    }
+    return adjacencyMap;
+  }
+
+  private static bfsReachable(seeds: string[], adj: Map<string, string[]>, reachable: Set<string>): void {
+    const queue = [...seeds];
+    for (const seed of seeds) {
+      reachable.add(seed);
+    }
+    while (queue.length > 0) {
+      const file = queue.shift()!;
+      for (const target of adj.get(file) ?? []) {
+        if (!reachable.has(target)) {
+          reachable.add(target);
+          queue.push(target);
+        }
+      }
+    }
+  }
+
   /**
    * Helper method to validate the schema collection.
    */

packages/ui/src/stubs/datamapper/data-mapper.ts

@@ -265,6 +265,12 @@ export function getMultiIncludeComponentAXsd(): string {
 export function getMultiIncludeComponentBXsd(): string {
   return readStubFile('./xml/MultiIncludeComponentB.xsd');
 }
+export function getCircularIncludeAXsd(): string {
+  return readStubFile('./xml/CircularIncludeA.xsd');
+}
+export function getCircularIncludeBXsd(): string {
+  return readStubFile('./xml/CircularIncludeB.xsd');
+}
 export function getInlineAttrSimpleTypeXsd(): string {
   return readStubFile('./xml/InlineAttrSimpleType.xsd');
 }

packages/ui/src/stubs/datamapper/xml/CircularIncludeA.xsd

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           targetNamespace="http://example.com/circular"
+           xmlns:tns="http://example.com/circular"
+           elementFormDefault="qualified">
+
+  <xs:include schemaLocation="CircularIncludeB.xsd"/>
+
+  <xs:element name="Root">
+    <xs:complexType>
+      <xs:sequence>
+        <xs:element name="order" type="tns:OrderType"/>
+      </xs:sequence>
+    </xs:complexType>
+  </xs:element>
+
+  <xs:complexType name="OrderType">
+    <xs:sequence>
+      <xs:element name="orderId" type="xs:string"/>
+      <xs:element name="product" type="tns:ProductType"/>
+    </xs:sequence>
+  </xs:complexType>
+
+</xs:schema>

packages/ui/src/stubs/datamapper/xml/CircularIncludeB.xsd

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           targetNamespace="http://example.com/circular"
+           xmlns:tns="http://example.com/circular"
+           elementFormDefault="qualified">
+
+  <xs:include schemaLocation="CircularIncludeA.xsd"/>
+
+  <xs:complexType name="ProductType">
+    <xs:sequence>
+      <xs:element name="productName" type="xs:string"/>
+      <xs:element name="price" type="xs:decimal"/>
+    </xs:sequence>
+  </xs:complexType>
+
+</xs:schema>