@likec4/core 1.17.1 → 1.18.0

package/src/compute-view/deployment-view/__test__/fixture.ts

@@ -0,0 +1,210 @@
+import { map, prop } from 'remeda'
+import { Builder } from '../../../builder'
+import type { DeploymentViewRuleBuilderOp } from '../../../builder/Builder.view'
+import { LikeC4Model } from '../../../model'
+import type { DeploymentView } from '../../../types'
+import { withReadableEdges } from '../../utils/with-readable-edges'
+import { computeDeploymentView } from '../compute'
+
+const {
+  builder: b,
+  model: {
+    model,
+    person,
+    system,
+    component,
+    webapp,
+    mobile,
+    ...$m
+  },
+  deployment: {
+    deployment,
+    env,
+    node,
+    zone,
+    instanceOf,
+    ...$d
+  },
+  views: {
+    view,
+    views,
+    viewOf,
+    deploymentView,
+    $rules,
+    $include,
+    $exclude,
+    $style
+  }
+} = Builder.forSpecification({
+  elements: {
+    person: {
+      style: {
+        shape: 'person'
+      }
+    },
+    system: {},
+    component: {},
+    webapp: {
+      style: {
+        shape: 'browser'
+      }
+    },
+    mobile: {
+      style: {
+        shape: 'mobile'
+      }
+    }
+  },
+  deployments: {
+    env: {},
+    zone: {},
+    node: {}
+  }
+})
+
+export const builder = b
+  .with(
+    model(
+      person('customer', {
+        title: 'Happy Customer'
+      }),
+      system('cloud').with(
+        component('frontend').with(
+          webapp('dashboard'),
+          mobile('mobile')
+        ),
+        component('auth'),
+        component('backend').with(
+          component('api')
+        ),
+        component('media', {
+          shape: 'storage'
+        })
+      ),
+      system('aws').with(
+        component('rds', {
+          shape: 'storage'
+        }),
+        component('s3', {
+          shape: 'storage'
+        })
+      ),
+      system('email')
+    ),
+    model(
+      $m.rel('customer', 'cloud', 'uses services'),
+      $m.rel('customer', 'cloud.frontend.mobile', 'opens mobile app'),
+      $m.rel('customer', 'cloud.frontend.dashboard', 'opens in browser'),
+      $m.rel('cloud.frontend.dashboard', 'cloud.auth', {
+        title: 'authenticates',
+        color: 'green'
+      }),
+      $m.rel('cloud.frontend.dashboard', 'cloud.backend.api', 'fetches data'),
+      $m.rel('cloud.frontend.dashboard', 'cloud.media', 'fetches media'),
+      $m.rel('cloud.frontend.mobile', 'cloud.auth', {
+        title: 'authenticates',
+        color: 'amber'
+      }),
+      $m.rel('cloud.frontend.mobile', 'cloud.backend.api', 'fetches data'),
+      $m.rel('cloud.frontend.mobile', 'cloud.media', 'fetches media'),
+      $m.rel('cloud.backend.api', 'cloud.auth', 'authorizes'),
+      $m.rel('cloud.backend.api', 'cloud.media', 'uploads media'),
+      $m.rel('cloud.backend.api', 'aws.rds', 'reads/writes'),
+      $m.rel('cloud.backend.api', 'email', 'sends emails'),
+      $m.rel('cloud.media', 'aws.s3', 'uploads'),
+      $m.rel('email', 'customer', 'sends emails')
+    ),
+    deployment(
+      node('customer').with(
+        instanceOf('instance', 'customer')
+      ),
+      env('prod').with(
+        zone('eu').with(
+          zone('zone1').with(
+            instanceOf('api', 'cloud.backend.api'),
+            instanceOf('ui', 'cloud.frontend.dashboard')
+          ),
+          zone('zone2').with(
+            instanceOf('api', 'cloud.backend.api'),
+            instanceOf('ui', 'cloud.frontend.dashboard')
+          ),
+          instanceOf('auth', 'cloud.auth'),
+          instanceOf('media', 'cloud.media'),
+          instanceOf('db', 'aws.rds')
+        ),
+        zone('us').with(
+          zone('zone1').with(
+            instanceOf('api', 'cloud.backend.api'),
+            instanceOf('ui', 'cloud.frontend.dashboard')
+          ),
+          instanceOf('db', 'aws.rds')
+        )
+      ),
+      env('acc').with(
+        node('testCustomer').with(
+          instanceOf('instance', 'customer')
+        ),
+        zone('eu').with(
+          instanceOf('api', 'cloud.backend.api'),
+          instanceOf('ui', 'cloud.frontend.dashboard'),
+          instanceOf('auth', 'cloud.auth'),
+          instanceOf('db', 'aws.rds')
+        )
+      ),
+      env('global').with(
+        instanceOf('email', 'email')
+      ),
+      $d.rel('prod.eu.db', 'prod.us.db', {
+        title: 'replicates',
+        color: 'green'
+      }),
+      $d.rel('prod.us.db', 'prod.eu.db', {
+        title: 'replicates',
+        color: 'amber'
+      })
+    )
+    // views(
+    //   view('index', $include('*')),
+    //   viewOf('cloud', 'cloud', $rules(
+    //     $include('*'),
+    //   )),
+    //   deploymentView('prod', $rules(
+    //     $include('customer.c'),
+    //     $include('prod._'),
+    //     $exclude('prod.eu.zone1 <-> prod.eu.zone2')
+    //   ))
+    // )
+  )
+
+export type Types = typeof builder['Types']
+
+export { $exclude, $include }
+
+export function computeView(...rules: DeploymentViewRuleBuilderOp<Types>[]) {
+  const modelsource = builder.with(
+    views(
+      deploymentView('index', $rules(...rules))
+    )
+  ).build()
+
+  const model = LikeC4Model.create({
+    ...modelsource,
+    views: {}
+  })
+
+  const view = withReadableEdges(computeDeploymentView(model, modelsource.views.index as DeploymentView))
+
+  return Object.assign(view, {
+    nodeIds: map(view.nodes, prop('id')) as string[],
+    edgeIds: map(view.edges, prop('id')) as string[]
+  })
+}
+
+export function computeNodesAndEdges(...rules: DeploymentViewRuleBuilderOp<Types>[]) {
+  const { nodeIds, edgeIds } = computeView(...rules)
+  return {
+    // Starts with capital letter to be first in snapshot
+    Nodes: nodeIds,
+    edges: edgeIds
+  }
+}

package/src/compute-view/deployment-view/_types.ts

@@ -0,0 +1,29 @@
+import { LikeC4DeploymentModel } from '../../model'
+import type { DeploymentConnectionModel } from '../../model/connection/deployment'
+import type { DeploymentElementModel } from '../../model/DeploymentElementModel'
+import type { AnyAux } from '../../model/types'
+import type { DeploymentExpression } from '../../types'
+import type { Memory, Patch } from './Memory'
+import type { Stage } from './Stage'
+
+export type Elem = DeploymentElementModel<AnyAux>
+
+export type Connections<M extends AnyAux = AnyAux> = ReadonlyArray<DeploymentConnectionModel<M>>
+
+export type PredicateParams<Expr extends DeploymentExpression = any> = {
+  expr: Expr
+  model: LikeC4DeploymentModel
+  stage: Stage
+  memory: Memory
+}
+
+export interface PredicateCtx {
+  model: LikeC4DeploymentModel
+  stage: Stage
+  memory: Memory
+}
+
+export interface PredicateExecutor<Expr extends DeploymentExpression> {
+  include(expr: Expr, ctx: PredicateCtx): Patch
+  exclude(expr: Expr, ctx: PredicateCtx): Patch
+}

package/src/compute-view/deployment-view/clean-connections.ts

@@ -0,0 +1,229 @@
+import DefaultMap from 'mnemonist/default-map'
+import { dropWhile, filter, flatMap, forEach, forEachObj, groupBy, hasAtLeast, map, pipe, prop, sort } from 'remeda'
+import { mergeConnections } from '../../model/connection/deployment'
+import { DeploymentConnectionModel } from '../../model/connection/DeploymentConnectionModel'
+import { RelationshipsAccum } from '../../model/DeploymentElementModel'
+import type { RelationshipModel } from '../../model/RelationModel'
+import type { AnyAux } from '../../model/types'
+import { compareFqnHierarchically, isAncestor } from '../../utils'
+import { difference } from '../../utils/set'
+import type { Connections, Elem } from './_types'
+import { type Patch } from './Memory'
+
+const filterEmptyConnection = filter((c: DeploymentConnectionModel<any>) => c.nonEmpty())
+
+// We add '.' to distinguish between connections with boundary and without
+// This way we can sort them hierarchically
+const connectionBoundary = (conn: DeploymentConnectionModel<any>) => conn.boundary?.id ? `.${conn.boundary.id}` : ''
+
+function cleanCrossBoundary<M extends AnyAux>(connections: Connections<M>): Connections<M> {
+  // Keep only connections between leafs
+  // Also find connections based on same relation
+  const groupedByRelation = new DefaultMap<RelationshipModel<M>, Array<DeploymentConnectionModel<M>>>(() => [])
+  for (const conn of connections) {
+    for (const relation of conn.relations.model) {
+      groupedByRelation.get(relation).push(conn)
+    }
+  }
+
+  // DeploymentConnectionModel is immutables
+  // So we create new instances without excluded relations
+  const excludedRelations = new DefaultMap<
+    DeploymentConnectionModel<M>,
+    Set<RelationshipModel<M>>
+  >(() => new Set())
+
+  // In each group, find connected to same leaf
+  for (const [relation, sameRelationGroup] of groupedByRelation) {
+    if (!hasAtLeast(sameRelationGroup, 2)) {
+      continue
+    }
+
+    // Outgoing from same source
+    pipe(
+      sameRelationGroup,
+      flatMap(conn => [
+        { group: `$source-${conn.source.id}`, conn },
+        { group: `$target-${conn.target.id}`, conn }
+      ]),
+      groupBy(prop('group')),
+      forEachObj((connections) => {
+        if (connections.length < 2) {
+          return
+        }
+        pipe(
+          connections,
+          map(prop('conn')),
+          // Sort by hierarchy, first are deepest
+          sort((a, b) => compareFqnHierarchically(connectionBoundary(a), connectionBoundary(b)) * -1),
+          // Skip connections until we reach another boundary
+          dropWhile((conn, i, all) => i === 0 || conn.boundary === all[i - 1]!.boundary),
+          // Clean relations from the rest
+          forEach((conn) => {
+            excludedRelations.get(conn).add(relation)
+          })
+        )
+      })
+    )
+  }
+
+  return pipe(
+    connections,
+    map(conn => {
+      const excluded = excludedRelations.get(conn)
+      if (excluded && excluded.size > 0) {
+        const updated = new DeploymentConnectionModel(
+          conn.source,
+          conn.target,
+          new RelationshipsAccum(
+            difference(conn.relations.model, excluded),
+            conn.relations.deployment
+          )
+        )
+        return updated
+      }
+      return conn
+    }),
+    filterEmptyConnection
+  )
+}
+
+/**
+ * Remove relationships from connection model, that are already included in the connections between descendants.
+ * In other words - if there is same connection down the hierarchy.
+ *
+ * @returns New connection without redundant relationships
+ *          Connection may be empty if all relationships are redundant, in this case it should be removed
+ */
+function excludeRedundantRelationships<M extends AnyAux>(
+  connections: Connections<M>
+): Array<DeploymentConnectionModel<M>> {
+  return pipe(
+    connections,
+    map(connection => {
+      const { source, target } = connection
+
+      // Connection between instances is always explicit
+      if (source.isInstance() && target.isInstance()) {
+        return connection
+      }
+
+      let modelRelations = connection.relations.model
+      let deploymentRelations = connection.relations.deployment
+
+      for (const c of connections) {
+        if (
+          isAncestor(source.id, c.source.id) && isAncestor(target.id, c.target.id)
+          || isAncestor(source.id, c.source.id) && c.target.id === target.id
+          || isAncestor(target.id, c.target.id) && c.source.id === source.id
+        ) {
+          modelRelations = difference(modelRelations, c.relations.model)
+          deploymentRelations = difference(deploymentRelations, c.relations.deployment)
+        }
+      }
+
+      // if any set changed, return new connection
+      if (modelRelations !== connection.relations.model || deploymentRelations !== connection.relations.deployment) {
+        return new DeploymentConnectionModel(
+          source,
+          target,
+          new RelationshipsAccum(
+            modelRelations,
+            deploymentRelations
+          )
+        )
+      }
+
+      return connection
+    }),
+    filterEmptyConnection
+  )
+}
+/**
+ * This patch:
+ * 1. Keeps connections between leafs or having direct deployment relations
+ * 2. Removes cross-boundary model relations, that already exist inside boundaries
+ *    (e.g. prefer relations inside same deployment node over relations between nodes)
+ * 3. Removes implicit connections between elements, if their descendants have same connection
+ */
+export const cleanConnections: Patch = (memory) => {
+  if (memory.connections.length < 2) {
+    return memory
+  }
+
+  const leafs = new Set<Elem>()
+
+  for (const element of memory.elements) {
+    // Instance is always leaf
+    if (element.isInstance()) {
+      leafs.add(element)
+      continue
+    }
+    // Check if element is ancestor of any element in elements
+    let isLeaf = true
+    for (const el of memory.elements) {
+      if (isAncestor(element.id, el.id)) {
+        isLeaf = false
+        break
+      }
+    }
+    if (isLeaf) {
+      leafs.add(element)
+    }
+  }
+
+  const connectedElements = new Set<Elem>()
+
+  const connections = pipe(
+    memory.connections,
+    mergeConnections,
+    // Keep connections
+    // - between leafs
+    // - has direct deployment relation
+    filter(c => {
+      return (leafs.has(c.source) && leafs.has(c.target)) || c.hasDirectDeploymentRelation()
+    }),
+    cleanCrossBoundary,
+    excludeRedundantRelationships,
+    forEach((c) => {
+      connectedElements.add(c.source)
+      connectedElements.add(c.target)
+      if (c.boundary) {
+        connectedElements.add(c.boundary)
+      }
+    })
+  )
+
+  const isAncestorOfConnected = (el: Elem) => {
+    if (el.isInstance()) {
+      return false
+    }
+    for (const connected of connectedElements) {
+      if (isAncestor(el.id, connected.id)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  // Update memory
+  const newMemory = memory.clone()
+  newMemory.connections = connections
+
+  // Iterate over elements (preserving order) and pick:
+  // - explicitly included
+  // - connected elements
+  // - ancestors of connected elements
+  const finalElements = new Set<Elem>()
+  for (const el of newMemory.finalElements) {
+    if (
+      newMemory.isExplicit(el)
+      || connectedElements.has(el)
+      || isAncestorOfConnected(el)
+    ) {
+      finalElements.add(el)
+    }
+  }
+  newMemory.finalElements = finalElements
+  return newMemory
+}

package/src/compute-view/deployment-view/compute.ts

@@ -0,0 +1,111 @@
+import { findLast } from 'remeda'
+import { nonexhaustive } from '../../errors'
+import { type LikeC4DeploymentModel, LikeC4Model } from '../../model'
+import type { AnyAux } from '../../model/types'
+import type { DeploymentViewRule } from '../../types'
+import {
+  type ComputedDeploymentView,
+  DeploymentElementExpression,
+  DeploymentRelationExpression,
+  type DeploymentView,
+  isViewRuleAutoLayout,
+  isViewRulePredicate
+} from '../../types'
+import { linkNodesWithEdges } from '../utils/link-nodes-with-edges'
+import { topologicalSort } from '../utils/topological-sort'
+import { calcViewLayoutHash } from '../utils/view-hash'
+import { cleanConnections } from './clean-connections'
+import { MutableMemory, type Patch } from './Memory'
+import { DeploymentRefPredicate } from './predicates/deployment-ref'
+import { DirectRelationPredicate } from './predicates/relation-direct'
+import { InOutRelationPredicate } from './predicates/relation-in-out'
+import { IncomingRelationPredicate } from './predicates/relation-incoming'
+import { OutgoingRelationPredicate } from './predicates/relation-outgoing'
+import { WildcardPredicate } from './predicates/wildcard'
+import { Stage } from './Stage'
+import { applyDeploymentViewRuleStyles, buildNodes, toComputedEdges } from './utils'
+
+function processPredicates<M extends AnyAux>(
+  model: LikeC4DeploymentModel<M>,
+  rules: DeploymentViewRule[]
+) {
+  let memory = MutableMemory.empty()
+  let stage: Stage | null = null
+
+  for (const rule of rules) {
+    if (isViewRulePredicate(rule)) {
+      const op = 'include' in rule ? 'include' : 'exclude'
+      const exprs = rule.include ?? rule.exclude
+      for (const expr of exprs) {
+        stage = new Stage(stage)
+        const ctx = { model, stage, memory }
+        let patch: Patch | undefined
+        switch (true) {
+          case DeploymentElementExpression.isRef(expr):
+            patch = DeploymentRefPredicate[op](expr, ctx)
+            break
+          case DeploymentElementExpression.isWildcard(expr):
+            patch = WildcardPredicate[op](expr, ctx)
+            break
+          case DeploymentRelationExpression.isDirect(expr):
+            patch = DirectRelationPredicate[op](expr, ctx)
+            break
+          case DeploymentRelationExpression.isInOut(expr):
+            patch = InOutRelationPredicate[op](expr, ctx)
+            break
+          case DeploymentRelationExpression.isOutgoing(expr):
+            patch = OutgoingRelationPredicate[op](expr, ctx)
+            break
+          case DeploymentRelationExpression.isIncoming(expr):
+            patch = IncomingRelationPredicate[op](expr, ctx)
+            break
+          default:
+            nonexhaustive(expr)
+        }
+        patch ??= stage.patch()
+        memory = patch(memory)
+      }
+    }
+  }
+  return cleanConnections(memory)
+}
+
+export function computeDeploymentView<M extends AnyAux>(
+  likec4model: LikeC4Model<M>,
+  {
+    docUri: _docUri, // exclude docUri
+    rules, // exclude rules
+    ...view
+  }: DeploymentView
+): ComputedDeploymentView<M['ViewId']> {
+  const memory = processPredicates<M>(likec4model.deployment, rules)
+
+  const nodesMap = buildNodes(memory)
+
+  const computedEdges = toComputedEdges(memory.connections)
+
+  linkNodesWithEdges(nodesMap, computedEdges)
+
+  const sorted = topologicalSort({
+    nodes: [...nodesMap.values()],
+    edges: computedEdges
+  })
+
+  const nodes = applyDeploymentViewRuleStyles(
+    rules,
+    sorted.nodes
+  )
+
+  const autoLayoutRule = findLast(rules, isViewRuleAutoLayout)
+
+  return calcViewLayoutHash({
+    ...view,
+    autoLayout: {
+      direction: autoLayoutRule?.direction ?? 'TB',
+      ...(autoLayoutRule?.nodeSep && { nodeSep: autoLayoutRule.nodeSep }),
+      ...(autoLayoutRule?.rankSep && { rankSep: autoLayoutRule.rankSep })
+    },
+    nodes,
+    edges: sorted.edges
+  })
+}