@likec4/core 1.18.0 → 1.19.1

package/src/model/DeploymentElementModel.ts

@@ -3,44 +3,50 @@ import type { SetRequired } from 'type-fest'
 import { nonNullable } from '../errors'
 import {
   type ComputedDeploymentView,
-  DefaultElementShape,
-  DefaultThemeColor,
   type DeployedInstance,
+  type DeploymentElementStyle,
   type DeploymentNode,
   type DeploymentNodeKind,
   type DeploymentRelation,
   type ElementShape as C4ElementShape,
+  type IteratorLike,
   type Link,
-  type PhysicalElementStyle,
   type Tag,
   type Tag as C4Tag,
-  type ThemeColor
+  type ThemeColor,
+  DefaultElementShape,
+  DefaultThemeColor,
 } from '../types'
-import { commonAncestor, nameFromFqn } from '../utils'
+import { commonAncestor, hierarchyLevel } from '../utils'
 import { difference, intersection, union } from '../utils/set'
 import type { LikeC4DeploymentModel } from './DeploymentModel'
 import type { ElementModel } from './ElementModel'
 import type { RelationshipModel, RelationshipsIterator } from './RelationModel'
-import type { AnyAux, IncomingFilter, IteratorLike, OutgoingFilter } from './types'
+import type { AnyAux, IncomingFilter, OutgoingFilter } from './types'
 import type { LikeC4ViewModel } from './view/LikeC4ViewModel'
 
-export type DeploymentElementsIterator<M extends AnyAux> = IteratorLike<DeploymentElementModel<M>>
+export type DeploymentElementsIterator<M extends AnyAux> = IteratorLike<
+  DeploymentNodeModel<M> | DeployedInstanceModel<M>
+>
 export type DeployedInstancesIterator<M extends AnyAux> = IteratorLike<DeployedInstanceModel<M>>
 export type DeploymentNodesIterator<M extends AnyAux> = IteratorLike<DeploymentNodeModel<M>>
 
-export abstract class DeploymentElementModel<M extends AnyAux = AnyAux> {
+export type DeploymentElementModel<M extends AnyAux = AnyAux> = DeploymentNodeModel<M> | DeployedInstanceModel<M>
+
+abstract class AbstractDeploymentElementModel<M extends AnyAux = AnyAux> {
+  abstract readonly id: M['DeploymentFqn']
+  abstract readonly parent: DeploymentNodeModel<M> | null
+  abstract readonly title: string
+  abstract readonly hierarchyLevel: number
+
   abstract readonly $model: LikeC4DeploymentModel<M>
   abstract readonly $node: DeploymentNode | DeployedInstance
 
-  get id(): M['DeploymentFqn'] {
-    return this.$node.id
-  }
-
-  get style(): SetRequired<PhysicalElementStyle, 'shape' | 'color'> {
+  get style(): SetRequired<DeploymentElementStyle, 'shape' | 'color'> {
     return {
       shape: DefaultElementShape,
       color: DefaultThemeColor,
-      ...this.$node.style
+      ...this.$node.style,
     }
   }
 
@@ -56,10 +62,6 @@ export abstract class DeploymentElementModel<M extends AnyAux = AnyAux> {
     return this.$node.tags ?? []
   }
 
-  get title(): string {
-    return this.$node.title ?? nameFromFqn(this.id)
-  }
-
   get description(): string | null {
     return this.$node.description ?? null
   }
@@ -68,10 +70,6 @@ export abstract class DeploymentElementModel<M extends AnyAux = AnyAux> {
     return this.$node.technology ?? null
   }
 
-  get parent(): DeploymentNodeModel<M> | null {
-    return this.$model.parent(this)
-  }
-
   get links(): ReadonlyArray<Link> {
     return this.$node.links ?? []
   }
@@ -118,6 +116,18 @@ export abstract class DeploymentElementModel<M extends AnyAux = AnyAux> {
     return
   }
 
+  /**
+   * Resolve siblings of the element and its ancestors
+   *  (from root to closest)
+   */
+  public *descendingSiblings(): DeploymentElementsIterator<M> {
+    for (const ancestor of [...this.ancestors()].reverse()) {
+      yield* ancestor.siblings()
+    }
+    yield* this.siblings()
+    return
+  }
+
   public incoming(filter: IncomingFilter = 'all'): IteratorLike<DeploymentRelationModel<M>> {
     return this.$model.incoming(this, filter)
   }
@@ -153,6 +163,9 @@ export abstract class DeploymentElementModel<M extends AnyAux = AnyAux> {
    */
   public *views(): IteratorLike<LikeC4ViewModel<M, ComputedDeploymentView>> {
     for (const view of this.$model.views()) {
+      if (!view.isDeploymentView()) {
+        continue
+      }
       if (view.includesDeployment(this.id)) {
         yield view
       }
@@ -168,35 +181,46 @@ export abstract class DeploymentElementModel<M extends AnyAux = AnyAux> {
     return false
   }
 
-  public abstract outgoingFromModel(): RelationshipsIterator<M>
-  public abstract incomingFromModel(): RelationshipsIterator<M>
+  public abstract outgoingModelRelationships(): RelationshipsIterator<M>
+  public abstract incomingModelRelationships(): RelationshipsIterator<M>
 
   protected cachedOutgoing: RelationshipsAccum<M> | null = null
   protected cachedIncoming: RelationshipsAccum<M> | null = null
 
   public get allOutgoing(): RelationshipsAccum<M> {
-    this.cachedOutgoing ??= new RelationshipsAccum(
-      new Set(this.outgoingFromModel()),
-      new Set(this.outgoing())
+    this.cachedOutgoing ??= RelationshipsAccum.from(
+      new Set(this.outgoingModelRelationships()),
+      new Set(this.outgoing()),
     )
     return this.cachedOutgoing
   }
 
   public get allIncoming(): RelationshipsAccum<M> {
-    this.cachedIncoming ??= new RelationshipsAccum(
-      new Set(this.incomingFromModel()),
-      new Set(this.incoming())
+    this.cachedIncoming ??= RelationshipsAccum.from(
+      new Set(this.incomingModelRelationships()),
+      new Set(this.incoming()),
     )
     return this.cachedIncoming
   }
 }
 
-export class DeploymentNodeModel<M extends AnyAux = AnyAux> extends DeploymentElementModel<M> {
+export class DeploymentNodeModel<M extends AnyAux = AnyAux> extends AbstractDeploymentElementModel<M> {
+  override id: M['DeploymentFqn']
+  override title: string
+  override hierarchyLevel: number
+
   constructor(
     public readonly $model: LikeC4DeploymentModel<M>,
-    public readonly $node: DeploymentNode
+    public readonly $node: DeploymentNode,
   ) {
     super()
+    this.id = $node.id
+    this.title = $node.title
+    this.hierarchyLevel = hierarchyLevel($node.id)
+  }
+
+  get parent(): DeploymentNodeModel<M> | null {
+    return this.$model.parent(this)
   }
 
   get kind(): DeploymentNodeKind {
@@ -207,8 +231,8 @@ export class DeploymentNodeModel<M extends AnyAux = AnyAux> extends DeploymentEl
     return this.$model.children(this)
   }
 
-  public descendants(): DeploymentElementsIterator<M> {
-    return this.$model.descendants(this)
+  public descendants(sort: 'asc' | 'desc' = 'desc'): DeploymentElementsIterator<M> {
+    return this.$model.descendants(this, sort)
   }
 
   public override isDeploymentNode(): this is DeploymentNodeModel<M> {
@@ -219,7 +243,7 @@ export class DeploymentNodeModel<M extends AnyAux = AnyAux> extends DeploymentEl
    * Iterate over all instances nested in this deployment node.
    */
   public *instances(): DeployedInstancesIterator<M> {
-    for (const nested of this.descendants()) {
+    for (const nested of this.descendants('desc')) {
       if (nested.isInstance()) {
         yield nested
       }
@@ -254,16 +278,16 @@ export class DeploymentNodeModel<M extends AnyAux = AnyAux> extends DeploymentEl
     }
     const {
       outgoing,
-      incoming
+      incoming,
     } = (this._relationshipsFromInstances = {
       outgoing: new Set<RelationshipModel<M>>(),
-      incoming: new Set<RelationshipModel<M>>()
+      incoming: new Set<RelationshipModel<M>>(),
     })
     for (const instance of this.instances()) {
-      for (const r of instance.$element.outgoing()) {
+      for (const r of instance.element.outgoing()) {
         outgoing.add(r)
       }
-      for (const r of instance.$element.incoming()) {
+      for (const r of instance.element.incoming()) {
         incoming.add(r)
       }
     }
@@ -273,98 +297,127 @@ export class DeploymentNodeModel<M extends AnyAux = AnyAux> extends DeploymentEl
   /**
    * We return only relationships that are not already present in nested instances
    */
-  public override outgoingFromModel(): RelationshipsIterator<M> {
-    const {
-      outgoing,
-      incoming
-    } = this.relationshipsFromInstances()
-    return difference(outgoing, incoming).values()
+  public override outgoingModelRelationships(): RelationshipsIterator<M> {
+    return this.relationshipsFromInstances().outgoing.values()
   }
 
   /**
    * We return only relationships that are not already present in nested instances
    */
-  public override incomingFromModel(): RelationshipsIterator<M> {
+  public override incomingModelRelationships(): RelationshipsIterator<M> {
+    return this.relationshipsFromInstances().incoming.values()
+  }
+
+  /**
+   * Returns an iterator of relationships between nested instances
+   */
+  public internalModelRelationships(): ReadonlySet<RelationshipModel<M>> {
     const {
       outgoing,
-      incoming
+      incoming,
     } = this.relationshipsFromInstances()
-    return difference(incoming, outgoing).values()
+    return intersection(incoming, outgoing)
   }
 }
 
-export class DeployedInstanceModel<M extends AnyAux = AnyAux> extends DeploymentElementModel<M> {
+export class DeployedInstanceModel<M extends AnyAux = AnyAux> extends AbstractDeploymentElementModel<M> {
+  override readonly id: M['DeploymentFqn']
+  override readonly title: string
+  override readonly hierarchyLevel: number
+
   constructor(
     public readonly $model: LikeC4DeploymentModel<M>,
     public readonly $instance: DeployedInstance,
-    public readonly $element: ElementModel<M>
+    public readonly element: ElementModel<M>,
   ) {
     super()
-  }
-
-  override get parent(): DeploymentNodeModel<M> {
-    return nonNullable(this.$model.parent(this), `Parent of ${this.id} not found`)
+    this.id = $instance.id
+    this.title = $instance.title ?? element.title
+    this.hierarchyLevel = hierarchyLevel($instance.id)
   }
 
   get $node(): DeployedInstance {
     return this.$instance
   }
 
-  override get style(): SetRequired<PhysicalElementStyle, 'shape' | 'color'> {
-    const { icon, style } = this.$element.$element
+  get parent(): DeploymentNodeModel<M> {
+    return nonNullable(this.$model.parent(this), `Parent of ${this.id} not found`)
+  }
+
+  override get style(): SetRequired<DeploymentElementStyle, 'shape' | 'color'> {
+    const { icon, style } = this.element.$element
     return {
-      shape: this.$element.shape,
-      color: this.$element.color,
+      shape: this.element.shape,
+      color: this.element.color,
       ...icon && { icon },
       ...style,
-      ...this.$instance.style
+      ...this.$instance.style,
     }
   }
 
   override get shape(): C4ElementShape {
-    return this.$instance.style?.shape ?? this.$element.shape
+    return this.$instance.style?.shape ?? this.element.shape
   }
 
   override get color(): ThemeColor {
-    return this.$instance.style?.color as ThemeColor ?? this.$element.color
+    return this.$instance.style?.color as ThemeColor ?? this.element.color
   }
 
   override get tags(): ReadonlyArray<C4Tag> {
     return this.$instance.tags ?? []
   }
 
-  override get title(): string {
-    return this.$instance.title ?? this.$element.title
-  }
-
   override get description(): string | null {
-    return this.$instance.description ?? this.$element.description
+    return this.$instance.description ?? this.element.description
   }
 
   override get technology(): string | null {
-    return this.$instance.technology ?? this.$element.technology
+    return this.$instance.technology ?? this.element.technology
   }
 
   override get links(): ReadonlyArray<Link> {
-    return this.$instance.links ?? this.$element.links
+    return this.$instance.links ?? this.element.links
   }
 
   public override isInstance(): this is DeployedInstanceModel<M> {
     return true
   }
 
-  public override outgoingFromModel(): RelationshipsIterator<M> {
-    return this.$element.outgoing()
+  public override outgoingModelRelationships(): RelationshipsIterator<M> {
+    return this.element.outgoing()
   }
-  public override incomingFromModel(): RelationshipsIterator<M> {
-    return this.$element.incoming()
+  public override incomingModelRelationships(): RelationshipsIterator<M> {
+    return this.element.incoming()
+  }
+
+  /**
+   * Iterate over all views that include this instance.
+   * (Some views may include the parent deployment node instead of the instance.)
+   */
+  public override *views(): IteratorLike<LikeC4ViewModel<M, ComputedDeploymentView>> {
+    for (const view of this.$model.views()) {
+      if (!view.isDeploymentView()) {
+        continue
+      }
+      if (view.includesDeployment(this.id)) {
+        yield view
+        continue
+      }
+      // check if the view includes parent referecing this element
+      if (
+        view.includesDeployment(this.parent.id)
+        && this.parent.onlyOneInstance()
+      ) {
+        yield view
+      }
+    }
   }
 }
 
 export class NestedElementOfDeployedInstanceModel<M extends AnyAux> {
   constructor(
     public readonly instance: DeployedInstanceModel<M>,
-    public readonly element: ElementModel<M>
+    public readonly element: ElementModel<M>,
   ) {
   }
 
@@ -372,13 +425,13 @@ export class NestedElementOfDeployedInstanceModel<M extends AnyAux> {
     return this.instance.id
   }
 
-  get style(): SetRequired<PhysicalElementStyle, 'shape' | 'color'> {
+  get style(): SetRequired<DeploymentElementStyle, 'shape' | 'color'> {
     const { icon, style } = this.element.$element
     return {
       shape: this.element.shape,
       color: this.element.color,
       ...icon && { icon },
-      ...style
+      ...style,
     }
   }
 
@@ -414,14 +467,14 @@ export type DeploymentRelationEndpoint<M extends AnyAux> =
   | DeploymentElementModel<M>
   | NestedElementOfDeployedInstanceModel<M>
 
-export class DeploymentRelationModel<M extends AnyAux> {
+export class DeploymentRelationModel<M extends AnyAux = AnyAux> {
   public boundary: DeploymentNodeModel<M> | null
   public source: DeploymentRelationEndpoint<M>
   public target: DeploymentRelationEndpoint<M>
 
   constructor(
     public readonly $model: LikeC4DeploymentModel<M>,
-    public readonly $relationship: DeploymentRelation
+    public readonly $relationship: DeploymentRelation,
   ) {
     this.source = $model.deploymentRef($relationship.source)
     this.target = $model.deploymentRef($relationship.target)
@@ -480,13 +533,25 @@ export class DeploymentRelationModel<M extends AnyAux> {
 }
 
 export class RelationshipsAccum<M extends AnyAux> {
+  static empty<M extends AnyAux>(): RelationshipsAccum<M> {
+    return new RelationshipsAccum()
+  }
+  static from<M extends AnyAux>(
+    model: Iterable<RelationshipModel<M>> | undefined,
+    deployment?: Iterable<DeploymentRelationModel<M>>,
+  ): RelationshipsAccum<M> {
+    return new RelationshipsAccum(
+      new Set(model),
+      new Set(deployment),
+    )
+  }
   /**
    * @param model relationships from logical model
    * @param deployment relationships from deployment model
    */
   constructor(
-    public readonly model: ReadonlySet<RelationshipModel<M>>,
-    public readonly deployment: ReadonlySet<DeploymentRelationModel<M>>
+    public readonly model: ReadonlySet<RelationshipModel<M>> = new Set(),
+    public readonly deployment: ReadonlySet<DeploymentRelationModel<M>> = new Set(),
   ) {
   }
 
@@ -506,9 +571,9 @@ export class RelationshipsAccum<M extends AnyAux> {
    * Returns new Accum containing all the elements which are both in this and otherAccum
    */
   public intersect(otherAccum: RelationshipsAccum<M>): RelationshipsAccum<M> {
-    return new RelationshipsAccum(
+    return RelationshipsAccum.from(
       intersection(this.model, otherAccum.model),
-      intersection(this.deployment, otherAccum.deployment)
+      intersection(this.deployment, otherAccum.deployment),
     )
   }
 
@@ -516,9 +581,9 @@ export class RelationshipsAccum<M extends AnyAux> {
    * Returns new Accum containing all the elements which are both in this and otherAccum
    */
   public difference(otherAccum: RelationshipsAccum<M>): RelationshipsAccum<M> {
-    return new RelationshipsAccum(
+    return RelationshipsAccum.from(
       difference(this.model, otherAccum.model),
-      difference(this.deployment, otherAccum.deployment)
+      difference(this.deployment, otherAccum.deployment),
     )
   }
 
@@ -526,9 +591,9 @@ export class RelationshipsAccum<M extends AnyAux> {
    * Returns new Accum containing all the elements from both
    */
   public union(otherAccum: RelationshipsAccum<M>): RelationshipsAccum<M> {
-    return new RelationshipsAccum(
+    return RelationshipsAccum.from(
       union(this.model, otherAccum.model),
-      union(this.deployment, otherAccum.deployment)
+      union(this.deployment, otherAccum.deployment),
     )
   }
 }

package/src/model/DeploymentModel.ts

@@ -3,28 +3,29 @@ import { values } from 'remeda'
 import type { LiteralUnion } from 'type-fest'
 import { invariant, nonNullable } from '../errors'
 import {
-  type AnyLikeC4Model,
   type ComputedDeploymentView,
-  DeploymentElement,
   type DeploymentRef,
   type DeploymentRelation,
-  type Tag as C4Tag
+  type GenericLikeC4Model,
+  type IteratorLike,
+  type Tag as C4Tag,
+  DeploymentElement,
 } from '../types'
-import { ancestorsFqn, parentFqn } from '../utils/fqn'
+import { ancestorsFqn, parentFqn, sortParentsFirst } from '../utils/fqn'
 import { getOrCreate } from '../utils/getOrCreate'
 import { isString } from '../utils/guards'
 import {
-  DeployedInstanceModel,
   type DeployedInstancesIterator,
-  DeploymentElementModel,
+  type DeploymentElementModel,
   type DeploymentElementsIterator,
-  DeploymentNodeModel,
   type DeploymentNodesIterator,
+  DeployedInstanceModel,
+  DeploymentNodeModel,
   DeploymentRelationModel,
-  NestedElementOfDeployedInstanceModel
+  NestedElementOfDeployedInstanceModel,
 } from './DeploymentElementModel'
 import type { LikeC4Model } from './LikeC4Model'
-import { type AnyAux, getId, type IncomingFilter, type IteratorLike, type OutgoingFilter } from './types'
+import { type AnyAux, type IncomingFilter, type OutgoingFilter, getId } from './types'
 import type { LikeC4ViewModel } from './view/LikeC4ViewModel'
 
 export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
@@ -63,15 +64,15 @@ export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
 
   constructor(
     public readonly $model: LikeC4Model<M>,
-    public readonly $deployments: AnyLikeC4Model['deployments']
+    public readonly $deployments: GenericLikeC4Model['deployments'],
   ) {
-    for (const element of values($deployments.elements)) {
+    for (const element of sortParentsFirst(values($deployments.elements))) {
       const el = this.addElement(element)
       for (const tag of el.tags) {
         this.#allTags.get(tag).add(el)
       }
       if (el.isInstance()) {
-        this.#instancesOf.get(el.$element.id).add(el)
+        this.#instancesOf.get(el.element.id).add(el)
       }
     }
     for (const relation of values($deployments.relations)) {
@@ -83,7 +84,7 @@ export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
   }
 
   public element(el: M['DeploymentOrFqn']): DeploymentElementModel<M> {
-    if (el instanceof DeploymentElementModel) {
+    if (el instanceof DeploymentNodeModel || el instanceof DeployedInstanceModel) {
       return el
     }
     const id = getId(el)
@@ -256,10 +257,15 @@ export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
   /**
    * Get all descendant elements (i.e. children, children’s children, etc.)
    */
-  public *descendants(element: M['DeploymentOrFqn']): DeploymentElementsIterator<M> {
+  public *descendants(element: M['DeploymentOrFqn'], sort: 'asc' | 'desc' = 'desc'): DeploymentElementsIterator<M> {
     for (const child of this.children(element)) {
-      yield child
-      yield* this.descendants(child.id)
+      if (sort === 'asc') {
+        yield child
+        yield* this.descendants(child.id)
+      } else {
+        yield* this.descendants(child.id)
+        yield child
+      }
     }
     return
   }
@@ -270,7 +276,7 @@ export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
    */
   public *incoming(
     element: M['DeploymentOrFqn'],
-    filter: IncomingFilter = 'all'
+    filter: IncomingFilter = 'all',
   ): IteratorLike<DeploymentRelationModel<M>> {
     const id = getId(element)
     for (const rel of this.#incoming.get(id)) {
@@ -291,7 +297,7 @@ export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
    */
   public *outgoing(
     element: M['DeploymentOrFqn'],
-    filter: OutgoingFilter = 'all'
+    filter: OutgoingFilter = 'all',
   ): IteratorLike<DeploymentRelationModel<M>> {
     const id = getId(element)
     for (const rel of this.#outgoing.get(id)) {
@@ -311,8 +317,8 @@ export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
       throw new Error(`Element ${element.id} already exists`)
     }
     const el = DeploymentElement.isDeploymentNode(element)
-      ? new DeploymentNodeModel(this, element)
-      : new DeployedInstanceModel(this, element, this.$model.element(element.element))
+      ? new DeploymentNodeModel(this, Object.freeze(element))
+      : new DeployedInstanceModel(this, Object.freeze(element), this.$model.element(element.element))
     this.#elements.set(el.id, el)
     const parentId = parentFqn(el.id)
     if (parentId) {
@@ -332,7 +338,7 @@ export class LikeC4DeploymentModel<M extends AnyAux = AnyAux> {
     }
     const rel = new DeploymentRelationModel(
       this,
-      relation
+      Object.freeze(relation),
     )
     this.#relations.set(rel.id, rel)
     this.#incoming.get(rel.target.id).add(rel)