@api-client/core 0.11.11 → 0.12.0

package/build/src/modeling/DomainImpactAnalysis.js

@@ -1,21 +1,21 @@
-import { DataNamespaceKind, DataEntityKind, DataModelKind, DataPropertyKind, DataAssociationKind, } from '../models/kinds.js';
+import { DomainNamespaceKind, DomainEntityKind, DomainModelKind, DomainPropertyKind, DomainAssociationKind, DataDomainKind, } from '../models/kinds.js';
 /**
  * # 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`).
@@ -33,28 +33,29 @@ import { DataNamespaceKind, DataEntityKind, DataModelKind, DataPropertyKind, Dat
  *
  * ## 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.
@@ -79,21 +80,24 @@ import { DataNamespaceKind, DataEntityKind, DataModelKind, DataPropertyKind, Dat
  *
  * ## 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`
@@ -101,33 +105,34 @@ import { DataNamespaceKind, DataEntityKind, DataModelKind, DataPropertyKind, Dat
  *         -   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.",
@@ -135,7 +140,7 @@ import { DataNamespaceKind, DataEntityKind, DataModelKind, DataPropertyKind, Dat
  *     },
  *     {
  *       "key": "name",
- *       "kind": "DataPropertyKind",
+ *       "kind": "DomainPropertyKind",
  *       "type": "delete",
  *       "impact": "The property with key name will be deleted.",
  *       "blocking": false
@@ -155,26 +160,27 @@ import { DataNamespaceKind, DataEntityKind, DataModelKind, DataPropertyKind, Dat
  *
  * ## 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:**
@@ -188,12 +194,12 @@ import { DataNamespaceKind, DataEntityKind, DataModelKind, DataPropertyKind, Dat
  *
  * ## 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.
@@ -215,7 +221,7 @@ export class DomainImpactAnalysis {
         this.root = root;
         this.report = {
             key: '',
-            kind: DataNamespaceKind,
+            kind: DataDomainKind,
             impact: [],
             canProceed: false,
         };
@@ -234,26 +240,34 @@ 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) {
+        this.report = {
+            key,
+            kind: DomainNamespaceKind,
+            impact: [],
+            canProceed: true,
+        };
+        this.report.impact = this.createRemoveForeignNamespaceImpact(key);
         return this.report;
     }
     createDeleteImpact(key, kind, rootKey) {
         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 [];
@@ -269,24 +283,22 @@ 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;
     }
     deleteDataModelAnalysis(key, rootKey) {
         const result = [];
-        const model = this.root.findDataModel(key);
+        const model = this.root.findModel(key);
         if (!model) {
             return result;
         }
@@ -294,13 +306,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;
     }
     deleteEntityAnalysis(key, rootKey) {
@@ -313,80 +325,74 @@ 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;
     }
     deletePropertyAnalysis(key) {
@@ -399,7 +405,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;
@@ -414,26 +420,89 @@ 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;
     }
     kindToLabel(kind) {
         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';
         }
     }
+    createRemoveForeignNamespaceImpact(key) {
+        const result = [];
+        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);
+                            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;
+    }
 }
 //# sourceMappingURL=DomainImpactAnalysis.js.map