feat(model): Add indicator nodes for cycles in the dependency graph

When during construction of the dependency graph a cycle in the
dependencies is detected, add a special marker node for the package
that closes the cycle that does not have any dependencies. That way,
the referenced package is still visible in the graph, but the graph
remains free of cycles.

Signed-off-by: Oliver Heger <oliver.heger@bosch.com>

Author: oheger-bosch

model/src/main/kotlin/DependencyGraph.kt

@@ -367,7 +367,12 @@ data class DependencyGraphNode(
      * A list of [Issue]s that occurred handling this dependency.
      */
     val issues: List<Issue> = emptyList()
-)
+) {
+    /**
+     * Test whether this node is a special marker node to indicate a cycle in the dependency graph.
+     */
+    fun isCycleIndicator(): Boolean = isCycleIndicatorIndex(fragment)
+}
 
 /**
  * A data class representing an edge in the dependency graph.
@@ -383,6 +388,24 @@ data class DependencyGraphEdge(
     val to: Int
 )
 
+/**
+ * Constant of a bit mask used to add information about cycles to a fragment index. A node acting as cycle indicator
+ * has a fragment index greater than this value.
+ */
+private const val CYCLE_INDICATOR_MASK = 0xFFFF
+
+/**
+ * Check whether the given [fragmentIndex] indicates a marker node for a cycle in the dependency graph.
+ */
+fun isCycleIndicatorIndex(fragmentIndex: Int): Boolean = fragmentIndex > CYCLE_INDICATOR_MASK
+
+/**
+ * Return the plain index of the fragment referenced by the given [fragmentIndex] stripping any information about
+ * cycles. If the passed in [fragmentIndex] is not an indicator index for cycles, it is returned as is; otherwise,
+ * the fragment component is extracted.
+ */
+fun extractFragment(fragmentIndex: Int): Int = fragmentIndex and CYCLE_INDICATOR_MASK
+
 /**
  * Convert this [DependencyReference] to a [DependencyGraphNode].
  */

model/src/main/kotlin/utils/DependencyGraphBuilder.kt

@@ -21,6 +21,8 @@ package org.ossreviewtoolkit.model.utils
 
 import java.util.LinkedList
 
+import org.apache.logging.log4j.kotlin.logger
+
 import org.ossreviewtoolkit.model.DependencyGraph
 import org.ossreviewtoolkit.model.DependencyGraphEdge
 import org.ossreviewtoolkit.model.DependencyGraphNode
@@ -30,6 +32,8 @@ import org.ossreviewtoolkit.model.Issue
 import org.ossreviewtoolkit.model.Package
 import org.ossreviewtoolkit.model.PackageLinkage
 import org.ossreviewtoolkit.model.RootDependencyIndex
+import org.ossreviewtoolkit.model.extractFragment
+import org.ossreviewtoolkit.model.isCycleIndicatorIndex
 
 /**
  * Internal class to represent the result of a search in the dependency graph. The outcome of the search
@@ -138,6 +142,12 @@ class DependencyGraphBuilder<D>(
      */
     private val references = mutableMapOf<DependencyReference, D>()
 
+    /**
+     * A map for generating fragment indices for marker nodes that are added to the graph if cycles are detected. The
+     * key is a fragment index, the value is the number of cycles found in this fragment.
+     */
+    private val cycleCounts = mutableMapOf<Int, Int>()
+
     /**
      * Add the given [dependency] for the scope with the given [scopeName] to this builder. This function needs to be
      * called for all direct dependencies of all scopes. That way the builder gets sufficient information to construct
@@ -232,7 +242,8 @@ class DependencyGraphBuilder<D>(
         scopeName: String,
         dependency: D,
         transitive: Boolean,
-        processed: Set<D>
+        processed: Set<D>,
+        inCycle: Boolean = false
     ): DependencyReference? {
         val id = dependencyHandler.identifierFor(dependency)
         val issues = dependencyHandler.issuesFor(dependency).toMutableList()
@@ -248,13 +259,13 @@ class DependencyGraphBuilder<D>(
                     scopeName,
                     dependency,
                     issues,
-                    transitive,
-                    processed
+                    processed,
+                    inCycle
                 )
             }
 
             is DependencyGraphSearchResult.Incompatible ->
-                insertIntoNewFragment(id, index, scopeName, dependency, issues, transitive, processed)
+                insertIntoNewFragment(id, index, scopeName, dependency, issues, processed, inCycle)
         }
 
         return updateScopeMapping(scopeName, ref, transitive)
@@ -321,67 +332,85 @@ class DependencyGraphBuilder<D>(
     }
 
     /**
-     * Add a new fragment to the dependency graph for the [dependency] with the given [id] and [index], which may be
-     * [transitive] and belongs to the scope with the given [scopeName]. This function is called for dependencies that
-     * cannot be added to already existing fragments. Therefore, create a new fragment and add the [dependency] to it,
-     * together with its own dependencies. Store the given [issues] for the dependency. Use [processed] to detect
-     * cycles.
+     * Add a new fragment to the dependency graph for the [dependency] with the given [id] and [index], which belongs
+     * to the scope with the given [scopeName]. This function is called for dependencies that cannot be added to
+     * already existing fragments. Therefore, create a new fragment and add the [dependency] to it, together with its
+     * own dependencies. Store the given [issues] for the dependency. Use [processed] and [inCycle] to detect cycles.
      */
     private fun insertIntoNewFragment(
         id: Identifier,
         index: Int,
         scopeName: String,
         dependency: D,
         issues: List<Issue>,
-        transitive: Boolean,
-        processed: Set<D>
+        processed: Set<D>,
+        inCycle: Boolean
     ): DependencyReference? {
         val fragmentMapping = mutableMapOf<Int, DependencyReference>()
         val dependencyIndex = RootDependencyIndex(index, referenceMappings.size)
         referenceMappings += fragmentMapping
 
-        return insertIntoGraph(id, dependencyIndex, scopeName, dependency, issues, transitive, processed)
+        return insertIntoGraph(id, dependencyIndex, scopeName, dependency, issues, processed, inCycle)
     }
 
     /**
      * Insert the [dependency] with the given [id] and [RootDependencyIndex][index], which belongs to the scope with
-     * the given [scopeName] and may be [transitive] into the dependency graph. Insert the dependencies of this
-     * [dependency] recursively. Create a new [DependencyReference] for the dependency and initialize it with the list
-     * of [issues]. Use the given [processed] set to figure out cycles in the dependency graph. If such a cycle is
-     * detected, stop processing of further dependencies and return *null*.
+     * the given [scopeName] into the dependency graph. Insert the dependencies of this [dependency] recursively.
+     * Create a new [DependencyReference] for the dependency and initialize it with the list of [issues]. Use the given
+     * [processed] set and the [inCycle] flag to deal with cycles in the dependency graph. If such a cycle is detected,
+     * add a marker node for the affected package (with a special fragment index) that does not have further
+     * dependencies.
      */
     private fun insertIntoGraph(
         id: Identifier,
         index: RootDependencyIndex,
         scopeName: String,
         dependency: D,
         issues: List<Issue>,
-        transitive: Boolean,
-        processed: Set<D>
+        processed: Set<D>,
+        inCycle: Boolean
     ): DependencyReference? {
         val nextProcessed = processed + dependency
-        val transitiveDependencies = dependencyHandler.dependenciesFor(dependency)
-            .mapNotNullTo(mutableSetOf()) { dep ->
-                dep.takeUnless { it in nextProcessed }?.let {
-                    addDependencyToGraph(scopeName, dep, transitive = true, nextProcessed + dep)
+        val transitiveDependencies = if (inCycle) {
+            emptySet()
+        } else {
+            dependencyHandler.dependenciesFor(dependency)
+                .mapNotNullTo(mutableSetOf()) { dep ->
+                    addDependencyToGraph(
+                        scopeName,
+                        dep,
+                        transitive = true,
+                        nextProcessed + dep,
+                        inCycle = dep in nextProcessed
+                    )
                 }
+        }
+
+        val fragmentIndex = if (inCycle) {
+            fragmentIndexForCycle(index.fragment).also {
+                logger.info { "Cycle detected in dependency graph for package '${id.toCoordinates()}'." }
+                logger.info { "Adding marker node with fragment index $it." }
             }
+        } else {
+            index.fragment
+        }
 
         val fragmentMapping = referenceMappings[index.fragment]
-        if (index.root in fragmentMapping) {
-            // If this point is reached, the package has already been inserted when processing its dependencies.
-            // This means that there is a cyclic dependency. To handle this case correctly, the insert operation has
-            // to be started anew.
-            return addDependencyToGraph(scopeName, dependency, transitive, nextProcessed)
+        if (index.root in fragmentMapping && !startOfCycle(index)) {
+            // If this point is reached, the package has already been inserted when processing its dependencies, but
+            // no cycle has been found. To handle this case correctly, the insert operation has to be restarted; this
+            // should then find the already inserted node in the graph.
+            return addDependencyToGraph(scopeName, dependency, transitive = true, processed + dependency)
         }
 
         val ref = DependencyReference(
             pkg = index.root,
-            fragment = index.fragment,
+            fragment = fragmentIndex,
             dependencies = transitiveDependencies,
             linkage = dependencyHandler.linkageFor(dependency),
             issues = issues
         )
+
         fragmentMapping[index.root] = ref
         references[ref] = dependency
 
@@ -392,6 +421,16 @@ class DependencyGraphBuilder<D>(
         return ref
     }
 
+    /**
+     * Check whether the given [index] refers to a node that is the starting point of a cycle. This is the case if
+     * there is a corresponding cycle indicator node.
+     */
+    private fun startOfCycle(index: RootDependencyIndex): Boolean =
+        references.keys.any {
+            it.pkg == index.root && isCycleIndicatorIndex(it.fragment) &&
+                extractFragment(it.fragment) == index.fragment
+        }
+
     /**
      * Construct a [Package] for the given [id] that corresponds to the given [dependency]. If the package is already
      * available, nothing has to be done. Otherwise, create a new one and add it to the set managed by this object. If
@@ -419,6 +458,20 @@ class DependencyGraphBuilder<D>(
 
         return ref
     }
+
+    /**
+     * Generate a special fragment index for a node that indicates a cycle in the dependency graph. The combination of
+     * package ID and fragment index must be unique for all nodes in the graph. Therefore, marker nodes to indicate
+     * cycles require some special values here. Cycle indicator nodes have a fragment index greater than 65536 where
+     * the upper bits are just a counter to generate a unique value. Use the provided original [fragmentIndex] to
+     * obtain the corresponding counter. To find the fragment index of the original node (that starts the cycle), the
+     * upper 16 bits just have to be masked out.
+     */
+    private fun fragmentIndexForCycle(fragmentIndex: Int): Int {
+        val counter = cycleCounts.getOrDefault(fragmentIndex, 0) + 1
+        cycleCounts[fragmentIndex] = counter
+        return fragmentIndex + (counter shl 16)
+    }
 }
 
 /**