@api-client/core 0.11.11 → 0.12.0

package/src/modeling/DomainImpactAnalysis.ts

@@ -1,18 +1,20 @@
 import {
-  DataNamespaceKind,
-  DataEntityKind,
-  DataModelKind,
-  DataPropertyKind,
-  DataAssociationKind,
+  DomainNamespaceKind,
+  DomainEntityKind,
+  DomainModelKind,
+  DomainPropertyKind,
+  DomainAssociationKind,
+  DataDomainKind,
 } from '../models/kinds.js'
-import type { DataNamespace } from './DataNamespace.js'
+import type { DataDomain } from './DataDomain.js'
 
 export type DomainImpactKinds =
-  | typeof DataNamespaceKind
-  | typeof DataEntityKind
-  | typeof DataModelKind
-  | typeof DataPropertyKind
-  | typeof DataAssociationKind
+  | typeof DomainNamespaceKind
+  | typeof DomainEntityKind
+  | typeof DomainModelKind
+  | typeof DomainPropertyKind
+  | typeof DomainAssociationKind
+  | typeof DataDomainKind
 
 /**
  * The impact analysis report
@@ -76,20 +78,20 @@ export interface DomainImpactItem {
 /**
  * # DomainImpactAnalysis
  *
- * The `DomainImpactAnalysis` class is a powerful tool for analyzing the consequences of deleting data domain objects
- * within a `DataNamespace`.
- * It helps developers understand the ripple effects of removing a namespace, data model, entity, property,
- * or association, ensuring data integrity and preventing unintended side effects.
+ * The `DomainImpactAnalysis` class is a tool for analyzing the consequences of deleting data domain elements
+ * within a `DataDomain`. It helps developers understand the ripple effects of removing a namespace, data model,
+ * entity, property, or association, ensuring data integrity and preventing unintended side effects.
  *
  * ## Core Concepts
  *
  * -   **Impact Report:** The central output of the `DomainImpactAnalysis` class is an `DomainImpactReport`.
  *     This report details the potential consequences of a deletion operation, including:
  *     -   The object being deleted (`key`, `kind`).
- *     -   A list of `ImpactItem` objects, each describing a specific consequence.
+ *     -   A list of `DomainImpactItem` objects, each describing a specific consequence.
  *     -   Whether the deletion can proceed safely (`canProceed`).
  *
- * -   **ImpactItem:** Each `ImpactItem` describes a specific consequence of the deletion. Key properties include:
+ * -   **DomainImpactItem:** Each `DomainImpactItem` describes a specific consequence of the deletion.
+ *     Key properties include:
  *     -   `key`: The key of the impacted object.
  *     -   `kind`: The kind of the impacted object.
  *     -   `type`: The type of impact (currently only `delete`).
@@ -107,28 +109,29 @@ export interface DomainImpactItem {
  *
  * ## Usage
  *
- * 1.  **Instantiation:** Create an instance of `DomainImpactAnalysis`, passing the root `DataNamespace` as an argument.
+ * 1.  **Instantiation:** Create an instance of `DomainImpactAnalysis`, passing the root `DataDomain` as an argument.
  *
  *     ```typescript
- *     import { DataNamespace } from './DataNamespace';
+ *     import { DataDomain } from './DataDomain';
  *     import { DomainImpactAnalysis } from './DomainImpactAnalysis';
  *
- *     const rootNamespace = new DataNamespace();
- *     // ... add some data to the namespace
- *     const analyzer = new DomainImpactAnalysis(rootNamespace);
+ *     const dataDomain = new DataDomain();
+ *     // ... add some data to the domain
+ *     const analyzer = new DomainImpactAnalysis(dataDomain);
  *     ```
  *
- * 2.  **Performing Analysis:** Use the `deleteAnalysis()` method to generate an `ImpactReport` for a specific deletion.
+ * 2.  **Performing Analysis:** Use the `deleteAnalysis()` method to generate an `DomainImpactReport` for
+ *     a specific deletion.
  *     Provide the `key` and `kind` of the object to be deleted.
  *
  *     ```typescript
- *     import { DataEntityKind } from '../models/kinds.js';
+ *     import { DomainEntityKind } from '../models/kinds.js';
  *     // ...
  *     const entityKey = 'some-entity-key';
- *     const report = analyzer.deleteAnalysis(entityKey, DataEntityKind);
+ *     const report = analyzer.deleteAnalysis(entityKey, DomainEntityKind);
  *     ```
  *
- * 3.  **Interpreting the Report:** Examine the `ImpactReport` to understand the consequences of the deletion.
+ * 3.  **Interpreting the Report:** Examine the `DomainImpactReport` to understand the consequences of the deletion.
  *     -   Check `report.canProceed` to see if the deletion is safe.
  *     -   Iterate through `report.impact` to understand each consequence.
  *     -   Pay special attention to `impact.blocking` to identify impacts that require manual resolution.
@@ -153,21 +156,24 @@ export interface DomainImpactItem {
  *
  * ## Supported Deletion Scenarios
  *
- * The `DomainImpactAnalysis` class supports analyzing the deletion of the following data domain object types:
+ * The `DomainImpactAnalysis` class supports analyzing the deletion of the following data domain element types:
  *
- * -   **Namespaces (`DataNamespaceKind`):** Deleting a namespace also impacts all its child namespaces,
- *     data models, entities, properties, and associations.
- * -   **Data Models (`DataModelKind`):** Deleting a data model impacts all its entities, properties, and associations.
- * -   **Entities (`DataEntityKind`):** Deleting an entity impacts its properties, associations, and any other
- *     entities that have it as a parent or target in an association.
- * -   **Properties (`DataPropertyKind`):** Deleting a property impacts the entity it belongs to.
- * -   **Associations (`DataAssociationKind`):** Deleting an association impacts the entity it belongs to.
+ * - **Namespaces (`DomainNamespaceKind`):** Deleting a namespace also impacts all its child namespaces,
+ *   data models, entities, properties, and associations.
+ * - **Data Models (`DomainModelKind`):** Deleting a data model impacts all its entities, properties, and associations.
+ * - **Entities (`DomainEntityKind`):** Deleting an entity impacts its properties, associations, and any other
+ *   entities that have it as a parent or target in an association.
+ * - **Properties (`DomainPropertyKind`):** Deleting a property impacts the entity it belongs to.
+ * - **Associations (`DomainAssociationKind`):** Deleting an association impacts the entity it belongs to.
+ * - **Data Domain (`DataDomainKind`):** Deleting a data domain is not supported.
  *
  * ## Example: Deleting an Entity
  *
  * Consider the following scenario:
  *
- * -   Namespace: `MyNamespace`
+ * ```
+ * DataDomain
+ *   - Namespace: `MyNamespace`
  *     -   Data Model: `ProductModel`
  *         -   Entity: `Product`
  *             -   Property: `name`
@@ -175,33 +181,34 @@ export interface DomainImpactItem {
  *         -   Entity: `Category`
  *             - Property: `name`
  *         - Entity: `SpecialProduct` (parent: `Product`)
+ * ```
  *
  * If you attempt to delete the `Product` entity, the `DomainImpactAnalysis` will generate a report similar to this:
  *
  * ```json
  * {
  *   "key": "Product",
- *   "kind": "DataEntityKind",
+ *   "kind": "DomainEntityKind",
  *   "impact": [
  *     {
  *       "key": "Product",
- *       "kind": "DataEntityKind",
+ *       "kind": "DomainEntityKind",
  *       "type": "delete",
  *       "impact": "The entity with key Product will be deleted.",
  *       "blocking": false
  *     },
  *     {
  *       "key": "SpecialProduct",
- *       "kind": "DataEntityKind",
+ *       "kind": "DomainEntityKind",
  *       "type": "delete",
  *       "impact": "The SpecialProduct entity will become an orphan because it is a child of Product.",
- *       "resolution": "The "Product" entity will be removed as the parent of the "SpecialProduct" entity.",
+ *       "resolution": "The \"Product\" entity will be removed as the parent of the \"SpecialProduct\" entity.",
  *       "blocking": true,
  *       "relationship": "child"
  *     },
  *     {
  *       "key": "category",
- *       "kind": "DataAssociationKind",
+ *       "kind": "DomainAssociationKind",
  *       "type": "delete",
  *       "impact": "The association with key category will be broken because it has a target to Product.",
  *       "resolution": "The association with key category will be removed from Product.",
@@ -209,7 +216,7 @@ export interface DomainImpactItem {
  *     },
  *     {
  *       "key": "name",
- *       "kind": "DataPropertyKind",
+ *       "kind": "DomainPropertyKind",
  *       "type": "delete",
  *       "impact": "The property with key name will be deleted.",
  *       "blocking": false
@@ -229,26 +236,27 @@ export interface DomainImpactItem {
  *
  * ## Types
  *
- * ### `ImpactKinds`
+ * ### `DomainImpactKinds`
  *
- * -   **Description:** A type alias for the kinds of data domain objects that can be analyzed.
+ * -   **Description:** A type alias for the kinds of data domain elements that can be analyzed.
  * -   **Values:**
- *     -   `DataNamespaceKind`
- *     -   `DataEntityKind`
- *     -   `DataModelKind`
- *     -   `DataPropertyKind`
- *     -   `DataAssociationKind`
+ *     - `DomainNamespaceKind`
+ *     - `DomainEntityKind`
+ *     - `DomainModelKind`
+ *     - `DomainPropertyKind`
+ *     - `DomainAssociationKind`
+ *     - `DataDomainKind`
  *
- * ### `ImpactReport`
+ * ### `DomainImpactReport`
  *
  * -   **Description:** The structure of the impact analysis report.
  * -   **Properties:**
  *     -   `key` (`string`): The key of the object being deleted.
- *     -   `kind` (`ImpactKinds`): The kind of the object being deleted.
- *     -   `impact` (`ImpactItem[]`): The list of impacts.
+ *     -   `kind` (`DomainImpactKinds`): The kind of the object being deleted.
+ *     -   `impact` (`DomainImpactItem[]`): The list of impacts.
  *     -   `canProceed` (`boolean`): Whether the deletion can proceed.
  *
- * ### `ImpactItem`
+ * ### `DomainImpactItem`
  *
  * -   **Description:** The structure of an individual impact item.
  * -   **Properties:**
@@ -262,12 +270,12 @@ export interface DomainImpactItem {
  *
  * ## Error Handling
  *
- * The `DomainImpactAnalysis` class does not throw errors. Instead, it uses the `ImpactReport` to communicate
+ * The `DomainImpactAnalysis` class does not throw errors. Instead, it uses the `DomainImpactReport` to communicate
  * the results of the analysis, including any blocking impacts.
  *
  * ## Best Practices
  *
- * - **Always Analyze Before Deleting:** Before deleting any data domain object, always use `DomainImpactAnalysis`
+ * - **Always Analyze Before Deleting:** Before deleting any data domain element, always use `DomainImpactAnalysis`
  *   to understand the consequences.
  * - **Handle Blocking Impacts:** Pay close attention to `blocking` impacts and implement appropriate
  *   logic to handle them.
@@ -284,13 +292,13 @@ export interface DomainImpactItem {
  */
 export class DomainImpactAnalysis {
   private report: DomainImpactReport
-  private root: DataNamespace
+  private root: DataDomain
 
-  constructor(root: DataNamespace) {
+  constructor(root: DataDomain) {
     this.root = root
     this.report = {
       key: '',
-      kind: DataNamespaceKind,
+      kind: DataDomainKind,
       impact: [],
       canProceed: false,
     }
@@ -310,27 +318,36 @@ export class DomainImpactAnalysis {
       canProceed: true,
     }
     this.report.impact = this.createDeleteImpact(key, kind, key)
-    // this.report.impact.unshift({
-    //   key,
-    //   kind,
-    //   type: 'delete',
-    //   impact: `The ${this.kindToLabel(kind)} with key ${key} will be deleted.`,
-    //   blocking: false,
-    // })
+    return this.report
+  }
+
+  /**
+   * Generates a report of how the data domain will be impacted by the removal of a foreign namespace.
+   * @param key The key of the foreign namespace.
+   * @returns The delete impact analysis report.
+   */
+  removeForeignNamespaceAnalysis(key: string): DomainImpactReport {
+    this.report = {
+      key,
+      kind: DomainNamespaceKind,
+      impact: [],
+      canProceed: true,
+    }
+    this.report.impact = this.createRemoveForeignNamespaceImpact(key)
     return this.report
   }
 
   protected createDeleteImpact(key: string, kind: DomainImpactKinds, rootKey: string): DomainImpactItem[] {
     switch (kind) {
-      case DataNamespaceKind:
+      case DomainNamespaceKind:
         return this.deleteNamespaceAnalysis(key, rootKey)
-      case DataModelKind:
+      case DomainModelKind:
         return this.deleteDataModelAnalysis(key, rootKey)
-      case DataEntityKind:
+      case DomainEntityKind:
         return this.deleteEntityAnalysis(key, rootKey)
-      case DataPropertyKind:
+      case DomainPropertyKind:
         return this.deletePropertyAnalysis(key)
-      case DataAssociationKind:
+      case DomainAssociationKind:
         return this.deleteAssociationAnalysis(key)
       default:
         return []
@@ -347,25 +364,23 @@ export class DomainImpactAnalysis {
       key: ns.key,
       kind: ns.kind,
       type: 'delete',
-      impact: `The ${ns.info.renderLabel} ${this.kindToLabel(DataNamespaceKind)} will be deleted.`,
+      impact: `The ${ns.info.getLabel()} ${this.kindToLabel(DomainNamespaceKind)} will be deleted.`,
       blocking: false,
     })
-    const namespaces = ns.listNamespaces()
-    namespaces.forEach((child) => {
+    for (const child of ns.listNamespaces()) {
       const items = this.deleteNamespaceAnalysis(child.key, rootKey)
       result.push(...items)
-    })
-    const models = ns.listDataModels()
-    models.forEach((child) => {
+    }
+    for (const child of ns.listModels()) {
       const items = this.deleteDataModelAnalysis(child.key, rootKey)
       result.push(...items)
-    })
+    }
     return result
   }
 
   protected deleteDataModelAnalysis(key: string, rootKey: string): DomainImpactItem[] {
     const result: DomainImpactItem[] = []
-    const model = this.root.findDataModel(key)
+    const model = this.root.findModel(key)
     if (!model) {
       return result
     }
@@ -373,13 +388,13 @@ export class DomainImpactAnalysis {
       key: model.key,
       kind: model.kind,
       type: 'delete',
-      impact: `The ${model.info.renderLabel} ${this.kindToLabel(DataModelKind)} will be deleted.`,
+      impact: `The ${model.info.getLabel()} ${this.kindToLabel(DomainModelKind)} will be deleted.`,
       blocking: false,
     })
-    model.entities.forEach((child) => {
+    for (const child of model.listEntities()) {
       const items = this.deleteEntityAnalysis(child.key, rootKey)
       result.push(...items)
-    })
+    }
     return result
   }
 
@@ -393,80 +408,76 @@ export class DomainImpactAnalysis {
       key: entity.key,
       kind: entity.kind,
       type: 'delete',
-      impact: `The ${entity.info.renderLabel} ${this.kindToLabel(DataEntityKind)} will be deleted.`,
+      impact: `The ${entity.info.getLabel()} ${this.kindToLabel(DomainEntityKind)} will be deleted.`,
       blocking: false,
     })
+
     // We need to know whether the entity is a parent of another entity
-    const children = this.root.definitions.entities.filter((domainEntity) => {
-      if (domainEntity.key === entity.key) {
-        // ignore self
-        return false
+    for (const info of this.root.graph.inEdges(key)) {
+      const edge = this.root.graph.edge(info)
+      if (!edge || edge.type !== 'parent') {
+        continue
       }
-      if (!domainEntity.parents.includes(entity.key)) {
-        // no relationship
-        return false
+      const childEntity = this.root.findEntity(info.v)
+      if (!childEntity) {
+        continue
       }
-      if (domainEntity.isChildOf(rootKey)) {
-        // No need to include this parent as it itself is being deleted
-        return false
+      if (childEntity.isChildOf(rootKey)) {
+        // No need to include this child as it itself is being deleted
+        continue
       }
-      // the entity has a parent-child relationship to the deleted entity.
-      return true
-    })
-    if (children.length) {
-      children.forEach((child) => {
-        const pLabel = entity.info.renderLabel
-        const cLabel = child.info.renderLabel
-        result.push({
-          key: child.key,
-          kind: child.kind,
-          type: 'delete',
-          impact: `The "${cLabel}" ${this.kindToLabel(DataEntityKind)} will become an orphan because it is a child of the "${pLabel}" entity.`,
-          resolution: `The "${pLabel}" entity will be removed as the parent of the "${cLabel}" entity.`,
-          blocking: true,
-          relationship: 'child',
-        })
+      const pLabel = entity.info.getLabel()
+      const cLabel = childEntity.info.getLabel()
+      result.push({
+        key: childEntity.key,
+        kind: childEntity.kind,
+        type: 'delete',
+        impact: `The "${cLabel}" ${this.kindToLabel(DomainEntityKind)} will become an orphan because it is a child of the "${pLabel}" entity.`,
+        resolution: `The "${pLabel}" entity will be removed as the parent of the "${cLabel}" entity.`,
+        blocking: true,
+        relationship: 'child',
       })
       this.report.canProceed = false
     }
     // We need to know whether there's another entity that has an association to this entity.
-    const inAssociations = this.root.definitions.associations.filter((association) => {
-      return association.targets.some((item) => {
-        if (item.key === entity.key) {
-          const related = association.getParentInstance()
-          if (!related) {
-            return false
-          }
-          if (related.isChildOf(rootKey)) {
-            // No need to include this association as the related entity itself is being deleted
-            return false
-          }
-          return true
-        }
-        return false
-      })
-    })
-    if (inAssociations.length) {
-      inAssociations.forEach((association) => {
-        result.push({
-          key: association.key,
-          kind: association.kind,
-          type: 'delete',
-          impact: `The ${association.info.renderLabel} ${this.kindToLabel(DataAssociationKind)} will be broken because it has a target to ${entity.info.renderLabel}.`,
-          resolution: `The ${association.info.renderLabel} ${this.kindToLabel(DataAssociationKind)} will be removed from ${entity.info.renderLabel}.`,
-          blocking: true,
-        })
+    for (const edgeInfo of this.root.graph.inEdges(entity.key)) {
+      const edge = this.root.graph.edge(edgeInfo)
+      if (!edge || edge.type !== 'association') {
+        continue
+      }
+      const association = this.root.findAssociation(edgeInfo.v)
+      if (!association) {
+        continue
+      }
+      const targetEntity = association.getParentInstance()
+      if (!targetEntity) {
+        continue
+      }
+      if (targetEntity.isChildOf(rootKey)) {
+        // No need to include this association as the target entity itself is being deleted
+        continue
+      }
+
+      const aLabel = association.info.getLabel()
+      const eLabel = entity.info.getLabel()
+      result.push({
+        key: association.key,
+        kind: association.kind,
+        type: 'delete',
+        impact: `The ${aLabel} ${this.kindToLabel(DomainAssociationKind)} will be broken because it has a target to ${eLabel}.`,
+        resolution: `The ${aLabel} ${this.kindToLabel(DomainAssociationKind)} will be removed from ${eLabel}.`,
+        blocking: true,
       })
       this.report.canProceed = false
     }
-    entity.properties.forEach((child) => {
+    for (const child of entity.listProperties()) {
       const items = this.deletePropertyAnalysis(child.key)
       result.push(...items)
-    })
-    entity.associations.forEach((child) => {
+    }
+    for (const child of entity.listAssociations()) {
       const items = this.deleteAssociationAnalysis(child.key)
       result.push(...items)
-    })
+    }
     return result
   }
 
@@ -480,7 +491,7 @@ export class DomainImpactAnalysis {
       key: property.key,
       kind: property.kind,
       type: 'delete',
-      impact: `The ${property.info.renderLabel} ${this.kindToLabel(DataPropertyKind)} will be deleted.`,
+      impact: `The ${property.info.getLabel()} ${this.kindToLabel(DomainPropertyKind)} will be deleted.`,
       blocking: false,
     })
     return result
@@ -496,7 +507,7 @@ export class DomainImpactAnalysis {
       key: association.key,
       kind: association.kind,
       type: 'delete',
-      impact: `The ${association.info.renderLabel} ${this.kindToLabel(DataAssociationKind)} will be deleted.`,
+      impact: `The ${association.info.getLabel()} ${this.kindToLabel(DomainAssociationKind)} will be deleted.`,
       blocking: false,
     })
     return result
@@ -504,18 +515,81 @@ export class DomainImpactAnalysis {
 
   protected kindToLabel(kind: DomainImpactKinds): string {
     switch (kind) {
-      case DataNamespaceKind:
+      case DomainNamespaceKind:
         return 'namespace'
-      case DataEntityKind:
+      case DomainEntityKind:
         return 'entity'
-      case DataModelKind:
+      case DomainModelKind:
         return 'data model'
-      case DataPropertyKind:
+      case DomainPropertyKind:
         return 'property'
-      case DataAssociationKind:
+      case DomainAssociationKind:
         return 'association'
       default:
         return 'unknown'
     }
   }
+
+  protected createRemoveForeignNamespaceImpact(key: string): DomainImpactItem[] {
+    const result: DomainImpactItem[] = []
+    const foreignNamespace = this.root.dependencies.get(key)
+    if (!foreignNamespace) {
+      return result
+    }
+    // Check for parent relationships to foreign entities
+    for (const entity of this.root.listEntities()) {
+      for (const info of this.root.graph.outEdges(entity.key)) {
+        const edge = this.root.graph.edge(info)
+        if (!edge) {
+          continue
+        }
+        if (edge.type === 'parent' && edge.domain === key) {
+          // the parent is in the foreign namespace
+          const parentEntity = this.root.findEntity(info.w)
+          if (!parentEntity) {
+            continue
+          }
+          const eLabel = entity.info.getLabel()
+          const pLabel = parentEntity.info.getLabel()
+          result.push({
+            key: entity.key,
+            kind: entity.kind,
+            type: 'delete',
+            impact: `The "${eLabel}" ${this.kindToLabel(DomainEntityKind)} will become an orphan because its parent "${pLabel}" is in the foreign namespace "${foreignNamespace.key}".`,
+            resolution: `The "${pLabel}" entity will be removed as the parent of the "${eLabel}" entity.`,
+            blocking: true,
+            relationship: 'child',
+          })
+          this.report.canProceed = false
+        } else if (edge.type === 'association') {
+          const association = this.root.findAssociation(info.w)
+          if (!association) {
+            continue
+          }
+          const targets = association.targets.filter((t) => t.domain === key)
+          if (targets.length) {
+            for (const info of targets) {
+              const targetEntity = this.root.findForeignEntity(info.key, info.domain as string)
+              if (!targetEntity) {
+                continue
+              }
+              const aLabel = association.info.getLabel()
+              const eLabel = entity.info.getLabel()
+              const tLabel = targetEntity.info.getLabel()
+              result.push({
+                key: association.key,
+                kind: association.kind,
+                type: 'delete',
+                impact: `The "${aLabel}" ${this.kindToLabel(DomainAssociationKind)} from "${eLabel}" will be broken because it targets "${tLabel}" in the foreign namespace "${foreignNamespace.key}".`,
+                resolution: `The "${aLabel}" ${this.kindToLabel(DomainAssociationKind)} will be removed from "${eLabel}".`,
+                blocking: true,
+              })
+              this.report.canProceed = false
+            }
+          }
+        }
+      }
+    }
+    return result
+  }
 }