@likec4/core 1.17.0 → 1.18.0

package/src/compute-view/utils/resolve-extended-views.ts

@@ -0,0 +1,65 @@
+import { first, last, values } from 'remeda'
+import { isExtendsElementView, type LikeC4View } from '../../types/view'
+import { findCycles, Graph, isAcyclic, postorder } from '../../utils/graphlib'
+
+/**
+ * Resolve rules of extended views
+ * (Removes invalid views)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function resolveRulesExtendedViews<V extends Record<any, LikeC4View>>(
+  unresolvedViews: V
+): V {
+  const g = new Graph({
+    directed: true,
+    multigraph: false,
+    compound: false
+  })
+  for (const view of values(unresolvedViews)) {
+    g.setNode(view.id, view.id)
+    if (isExtendsElementView(view)) {
+      // view -> parent
+      g.setEdge(view.id, view.extends)
+    }
+  }
+  if (g.edgeCount() === 0) {
+    return unresolvedViews
+  }
+
+  // Remove circular dependencies
+  while (!isAcyclic(g)) {
+    const firstCycle = first(findCycles(g))
+    if (!firstCycle) {
+      break
+    }
+    const cycledNode = last(firstCycle)
+    if (!cycledNode) {
+      break
+    }
+    g.removeNode(cycledNode)
+  }
+
+  const ordered = postorder(g, g.sources() as unknown as string[])
+
+  return ordered.reduce((acc, id) => {
+    const view = unresolvedViews[id]
+    if (!view) {
+      return acc
+    }
+    if (isExtendsElementView(view)) {
+      const extendsFrom = acc[view.extends]
+      if (!extendsFrom) {
+        console.warn(`View "${view.id}" extends from "${view.extends}" which does not exist`)
+        return acc
+      }
+      return Object.assign(acc, {
+        [view.id]: {
+          ...extendsFrom,
+          ...view,
+          rules: [...extendsFrom.rules, ...view.rules]
+        }
+      })
+    }
+    return Object.assign(acc, { [view.id]: view })
+  }, {} as V)
+}

package/src/compute-view/utils/resolve-global-rules.ts

@@ -0,0 +1,83 @@
+import { isNullish } from 'remeda'
+import { nonexhaustive } from '../../errors'
+import {
+  type DynamicView,
+  type DynamicViewRule,
+  type ElementView,
+  isDynamicView,
+  isElementView,
+  isViewRuleGlobalPredicateRef,
+  isViewRuleGlobalStyle,
+  type ModelGlobals,
+  type ViewRule,
+  type ViewRuleGlobalPredicateRef,
+  type ViewRuleGlobalStyle
+} from '../../types'
+
+export function resolveGlobalRules<V extends DynamicView | ElementView>(
+  view: V,
+  globals: ModelGlobals
+): V {
+  if (isElementView(view)) {
+    return {
+      ...view,
+      rules: resolveGlobalRulesInElementView(view, globals)
+    }
+  } else if (isDynamicView(view)) {
+    return {
+      ...view,
+      rules: resolveGlobalRulesInDynamicView(view, globals)
+    }
+  }
+  nonexhaustive(view)
+}
+
+type ViewRuleGlobal = ViewRuleGlobalPredicateRef | ViewRuleGlobalStyle
+
+export function resolveGlobalRulesInElementView(
+  view: ElementView,
+  globals: ModelGlobals
+): Array<Exclude<ViewRule, ViewRuleGlobal>> {
+  return view.rules.reduce((acc, rule) => {
+    if (isViewRuleGlobalPredicateRef(rule)) {
+      const globalPredicates = globals.predicates[rule.predicateId]
+      if (isNullish(globalPredicates)) {
+        return acc
+      }
+      return acc.concat(globalPredicates)
+    }
+    if (isViewRuleGlobalStyle(rule)) {
+      const globalStyles = globals.styles[rule.styleId]
+      if (isNullish(globalStyles)) {
+        return acc
+      }
+      return acc.concat(globalStyles)
+    }
+    acc.push(rule)
+    return acc
+  }, [] as Array<Exclude<ViewRule, ViewRuleGlobal>>)
+}
+
+export function resolveGlobalRulesInDynamicView(
+  view: DynamicView,
+  globals: ModelGlobals
+): Array<Exclude<DynamicViewRule, ViewRuleGlobal>> {
+  return view.rules.reduce((acc, rule) => {
+    if (isViewRuleGlobalPredicateRef(rule)) {
+      const globalPredicates = globals.dynamicPredicates[rule.predicateId]
+      if (isNullish(globalPredicates)) {
+        return acc
+      }
+      return acc.concat(globalPredicates)
+    }
+    if (isViewRuleGlobalStyle(rule)) {
+      const globalStyles = globals.styles[rule.styleId]
+      if (isNullish(globalStyles)) {
+        return acc
+      }
+      return acc.concat(globalStyles)
+    }
+    acc.push(rule)
+    return acc
+  }, [] as Array<Exclude<DynamicViewRule, ViewRuleGlobal>>)
+}

package/src/compute-view/utils/sortNodes.ts

@@ -0,0 +1,101 @@
+import { difference, filter, map, pipe, sort, tap } from 'remeda'
+import { invariant, nonNullable } from '../../errors'
+import type { Fqn } from '../../types/element'
+import type { ComputedEdge, ComputedNode, EdgeId } from '../../types/view'
+import { compareByFqnHierarchically } from '../../utils/fqn'
+import { Graph, postorder } from '../../utils/graphlib'
+import { compareRelations } from '../../utils/relations'
+
+// side effect
+function sortChildren(nodes: readonly ComputedNode[]) {
+  nodes.forEach(parent => {
+    if (parent.children.length > 0) {
+      parent.children = nodes.flatMap(n => (n.parent === parent.id ? n.id : []))
+    }
+  })
+}
+
+export function sortNodes({
+  nodes,
+  edges
+}: {
+  nodes: ComputedNode[]
+  edges: ComputedEdge[]
+}): ComputedNode[] {
+  if (nodes.length < 2) {
+    return nodes
+  }
+  if (edges.length === 0) {
+    return pipe(
+      nodes,
+      sort(compareByFqnHierarchically),
+      tap(sortChildren)
+    )
+  }
+
+  const g = new Graph({
+    compound: false,
+    directed: true,
+    multigraph: false
+  })
+
+  const getNode = (id: Fqn) =>
+    nonNullable(
+      nodes.find(n => n.id === id),
+      'Edge not found'
+    )
+  const getEdge = (id: EdgeId) =>
+    nonNullable(
+      edges.find(edge => edge.id === id),
+      'Edge not found'
+    )
+
+  for (const e of [...edges].sort(compareRelations)) {
+    g.setEdge(e.source, e.target)
+  }
+
+  for (const n of nodes) {
+    g.setNode(n.id, n.id)
+    if (n.children.length > 0) {
+      n.inEdges.forEach(e => {
+        const edge = getEdge(e)
+        // if this edge from leaf to the child of this node
+        if (edge.target !== n.id && getNode(edge.source).children.length === 0) {
+          // const id = `${edge.source}:${n.id}`
+          g.setEdge(edge.source, n.id)
+        }
+      })
+      // n.outEdges.forEach(e => {
+      //   const edge = getEdge(e)
+      //   if (edge.source !== n.id) {
+      //     const id = `${n.id}:${edge.target}`
+      //     g.setEdge(n.id, edge.target, undefined, id)
+      //   }
+      // })
+    }
+    if (n.parent) {
+      g.setEdge(n.parent, n.id)
+    }
+  }
+
+  let sources = g.sources() as unknown as Fqn[]
+  if (sources.length === 0) {
+    sources = pipe(
+      nodes,
+      filter(n => n.inEdges.length === 0 || n.parent === null),
+      sort(compareByFqnHierarchically),
+      map(n => n.id)
+    )
+  }
+  // sources = sources.sort(compareFqnHierarchically)
+  const orderedIds = postorder(g, sources).reverse() as Fqn[]
+  const sorted = orderedIds.map(getNode)
+  if (sorted.length < nodes.length) {
+    const unsorted = difference(nodes, sorted).sort(compareByFqnHierarchically)
+    sorted.push(...unsorted)
+  }
+
+  invariant(sorted.length === nodes.length, 'Not all nodes were processed by graphlib')
+  sortChildren(sorted)
+  return sorted
+}

package/src/compute-view/utils/topological-sort.ts

@@ -0,0 +1,160 @@
+import Graph from 'graphology'
+import { topologicalSort as topsort } from 'graphology-dag/topological-sort'
+import willCreateCycle from 'graphology-dag/will-create-cycle'
+import { forEach, map, pipe, prop, sortBy } from 'remeda'
+import { invariant, nonNullable } from '../../errors'
+import type { ComputedEdge, ComputedNode, NodeId } from '../../types'
+
+/**
+ * Keeps initial order of the elements, but ensures that parents are before children
+ */
+function ensureParentsFirst<T extends { id: string; parent: string | null }>(
+  array: ReadonlyArray<T>
+): Array<T> {
+  const result = [] as T[]
+  const items = [...array]
+  let item
+  while ((item = items.shift())) {
+    let parent = item.parent
+    if (parent) {
+      const ancestors = [] as T[]
+      while (parent) {
+        const parentIndx = items.findIndex(i => i.id === parent)
+        if (parentIndx < 0) {
+          break
+        }
+        const [parentItem] = items.splice(parentIndx, 1)
+        if (!parentItem) {
+          throw new Error('Invalid state, should not happen')
+        }
+        ancestors.unshift(parentItem)
+        parent = parentItem.parent
+      }
+      result.push(...ancestors)
+    }
+    result.push(item)
+  }
+  return result as Array<T>
+}
+
+/**
+ * Side effect, mutates node.children field to preserve same order as in the input
+ */
+function updateChildren(nodes: ComputedNode[]) {
+  nodes.forEach(parent => {
+    if (parent.children.length > 0) {
+      parent.children = nodes.reduce((acc, n) => {
+        if (n.parent === parent.id) {
+          acc.push(n.id)
+        }
+        return acc
+      }, [] as NodeId[])
+    }
+  })
+  return nodes
+}
+
+type TopologicalSortParam = {
+  nodes: Iterable<ComputedNode>
+  edges: Iterable<ComputedEdge>
+}
+export function topologicalSort(
+  param: TopologicalSortParam
+): {
+  nodes: ComputedNode[]
+  edges: ComputedEdge[]
+} {
+  let nodes = [...param.nodes]
+  let edges = [...param.edges]
+  if (nodes.length < 2) {
+    return {
+      nodes,
+      edges
+    }
+  }
+  nodes = ensureParentsFirst(nodes)
+
+  if (edges.length === 0) {
+    return {
+      nodes,
+      edges
+    }
+  }
+
+  const getNode = (id: string) => nonNullable(nodes.find(n => n.id === id))
+  const nodeLevel = (id: string) => getNode(id).level + 1
+  const getEdge = (id: string) => nonNullable(edges.find(edge => edge.id === id))
+
+  const g = new Graph({
+    multi: true,
+    allowSelfLoops: true,
+    type: 'directed'
+  })
+
+  for (const n of nodes) {
+    g.addNode(n.id)
+  }
+  const sortedEdges = [] as ComputedEdge[]
+
+  pipe(
+    edges,
+    map(e => ({
+      e,
+      parentLevel: e.parent ? nodeLevel(e.parent) : 0,
+      sourceLevel: nodeLevel(e.source),
+      targetLevel: nodeLevel(e.target),
+      sourceIndex: nodes.findIndex(n => n.id === e.source),
+      targetIndex: nodes.findIndex(n => n.id === e.target)
+    })),
+    sortBy(
+      [prop('parentLevel'), 'desc'],
+      [prop('sourceLevel'), 'desc'],
+      [prop('targetLevel'), 'desc'],
+      [prop('sourceIndex'), 'asc'],
+      [prop('targetIndex'), 'asc']
+    ),
+    forEach(({ e }, idx, _all) => {
+      sortedEdges.push(e)
+      if (idx === 0 || !willCreateCycle(g, e.source, e.target)) {
+        g.mergeDirectedEdge(e.source, e.target)
+      }
+    })
+  )
+
+  // Strengthen the graph by adding edges to compound nodes
+  for (const n of nodes) {
+    if (n.children.length > 0) {
+      n.inEdges.forEach(e => {
+        const edge = getEdge(e)
+        // if this edge from leaf to the child of this node
+        if (edge.target !== n.id && getNode(edge.source).children.length === 0) {
+          if (!willCreateCycle(g, edge.source, n.id)) {
+            g.mergeDirectedEdge(edge.source, n.id)
+          }
+        }
+      })
+    }
+    if (n.parent && !willCreateCycle(g, n.parent, n.id)) {
+      g.mergeDirectedEdge(n.parent, n.id)
+    }
+  }
+
+  const sortedIds = topsort(g)
+  const sorted = [] as ComputedNode[]
+  for (const sortedId of sortedIds) {
+    const indx = nodes.findIndex(n => n.id === sortedId)
+    invariant(indx >= 0, `Node "${sortedId}" not found`)
+    sorted.push(...nodes.splice(indx, 1))
+  }
+  if (nodes.length > 0) {
+    sorted.push(...nodes)
+  }
+  return {
+    nodes: pipe(
+      sorted,
+      ensureParentsFirst,
+      updateChildren
+    ),
+    edges: sortedEdges
+  }
+}

package/src/compute-view/utils/uniqueTags.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { uniqueTags } from './uniqueTags'
+
+describe('uniqueTags function', () => {
+  it('returns unique tags from an array of elements', () => {
+    const input = [
+      { tags: ['tag1', 'tag2', 'tag3'] },
+      { tags: ['tag2', 'tag3', 'tag4'] },
+      { tags: ['tag3', 'tag4', 'tag5'] }
+    ] as const
+    const result = uniqueTags(input)
+    expect(result).toEqual(['tag1', 'tag2', 'tag3', 'tag4', 'tag5'])
+  })
+
+  it('should return unique tags naturally sorted', () => {
+    const input = [
+      { tags: ['tag1', 'tag20', 'tag30'] },
+      { tags: ['tag2', 'tag23', 'tag34'] },
+      { tags: ['tag3'] }
+    ] as const
+    const result = uniqueTags(input)
+    expect(result).toEqual([
+      'tag1',
+      'tag2',
+      'tag3',
+      'tag20',
+      'tag23',
+      'tag30',
+      'tag34'
+    ])
+    // ].sort(compareNatural))
+  })
+
+  it('returns null if the tags array is null', () => {
+    const input = [
+      { tags: null },
+      {}
+    ]
+    const result = uniqueTags(input)
+    expect(result).toBeNull()
+  })
+})

package/src/compute-view/utils/uniqueTags.ts

@@ -0,0 +1,21 @@
+import { flatMap, hasAtLeast, pipe, sort, unique } from 'remeda'
+import type { LiteralUnion } from 'type-fest'
+import type { NonEmptyReadonlyArray } from '../../types/_common'
+import type { Tag } from '../../types/element'
+import { compareNatural } from '../../utils/compare-natural'
+
+/**
+ * Extracts unique tags from an array of elements.
+ * and sort in natural order; returns null if no tags are present.
+ */
+export function uniqueTags<T extends { tags?: NonEmptyReadonlyArray<LiteralUnion<Tag, string>> | null }>(
+  elements: ReadonlyArray<T>
+) {
+  const tags = pipe(
+    elements,
+    flatMap(e => e.tags ?? []),
+    unique(),
+    sort(compareNatural)
+  )
+  return hasAtLeast(tags, 1) ? tags as NonEmptyReadonlyArray<Tag> : null
+}

package/src/compute-view/utils/view-hash.ts

@@ -0,0 +1,27 @@
+import { isTruthy, map, mapToObj, pick, pipe } from 'remeda'
+import type { SetOptional } from 'type-fest'
+import type { ComputedView } from '../../types'
+import { objectHash } from '../../utils/object-hash'
+
+export function calcViewLayoutHash<V extends ComputedView>(view: SetOptional<V, 'hash'>): V {
+  const tohash = {
+    id: view.id,
+    __: view.__ ?? 'element',
+    autoLayout: view.autoLayout,
+    nodes: pipe(
+      view.nodes,
+      map(pick(['id', 'title', 'description', 'technology', 'shape', 'icon', 'children'])),
+      mapToObj(({ id, icon, ...node }) => [id, { ...node, icon: isTruthy(icon) ? 'Y' : 'N' }])
+    ),
+    edges: pipe(
+      view.edges,
+      map(pick(['source', 'target', 'label', 'description', 'technology', 'dir', 'head', 'tail', 'line'])),
+      mapToObj(({ source, target, ...edge }) => [`${source}:${target}`, edge])
+    )
+  }
+  view.hash = objectHash(tohash, {
+    ignoreUnknown: true,
+    respectType: false
+  })
+  return view as V
+}

package/src/compute-view/utils/with-readable-edges.ts

@@ -0,0 +1,31 @@
+import { map, mapToObj, mapValues } from 'remeda'
+import type { ComputedLikeC4Model } from '../../types'
+import type { ComputedView, EdgeId } from '../../types/view'
+
+/**
+ * Convert hashed edge ids to human-readable
+ * Mostly for testing purposes
+ */
+export function withReadableEdges<T extends ComputedView>({ edges, nodes, ...view }: T): T {
+  const edgeids = mapToObj(edges, e => [e.id, `${e.source}:${e.target}` as EdgeId])
+
+  return {
+    ...view,
+    edges: edges.map(e => ({
+      ...e,
+      id: edgeids[e.id]!
+    })),
+    nodes: nodes.map(n => ({
+      ...n,
+      inEdges: map(n.inEdges, e => edgeids[e]!),
+      outEdges: map(n.outEdges, e => edgeids[e]!)
+    }))
+  } as T
+}
+
+export function viewsWithReadableEdges<M extends ComputedLikeC4Model>({ views, ...model }: M): M {
+  return {
+    ...model,
+    views: mapValues(views, withReadableEdges)
+  } as M
+}

package/src/index.ts

@@ -6,11 +6,15 @@ export * from './errors'
 export * from './model'
 
 export * from './types'
-export * from './utils/commonHead'
+export * from './utils/common-head'
 export * from './utils/compare-natural'
 export * from './utils/fqn'
+export * from './utils/getOrCreate'
 export * from './utils/guards'
+export * from './utils/object-hash'
 export * from './utils/promises'
 export { compareRelations } from './utils/relations'
+export * from './utils/set'
+export * from './utils/string-hash'
 
 export * as Expr from './types/expression'