Feature/automated graph doc (#1171)

* Add automated Doc generation for Nodes and Relationships

* Add command line option to print Schema to a specified file

* Use css classes instead of repeating style

* Small renaming

* Automatically build schema on main

* Delete duplicate file

* Also list properties

* Ban inherited fields and properties to detail boxes

* Removing newlines in output to have all relationships share lines

* Remove github ci part

* Updated generated documentation

* sonar

* Formatting

* Add Option to print the schema into a different format

* Finish Json output and add more documentation to finalize the PR

* Remove old serialization of ast children edges

* Test that files are correctly written and in case of Json also parseable

---------

Co-authored-by: Alexander Kuechler <[email protected]>
Co-authored-by: KuechA <[email protected]>

cpg-core/src/main/kotlin/de/fraunhofer/aisec/cpg/helpers/neo4j/LocationConverter.kt

@@ -30,11 +30,20 @@ import de.fraunhofer.aisec.cpg.sarif.Region
 import java.net.URI
 import org.neo4j.ogm.typeconversion.CompositeAttributeConverter
 
+interface CpgCompositeConverter<A> : CompositeAttributeConverter<A> {
+    /**
+     * Determines to which properties and their types the received value will be split in the neo4j
+     * representation. The type is the first element in the pair and the property name is the second
+     * one.
+     */
+    val graphSchema: List<Pair<String, String>>
+}
+
 /**
- * This class converts a [PhysicalLocation] into the the necessary composite attributes when
- * persisting a node into a Neo4J graph database.
+ * This class converts a [PhysicalLocation] into the necessary composite attributes when persisting
+ * a node into a Neo4J graph database.
  */
-class LocationConverter : CompositeAttributeConverter<PhysicalLocation?> {
+class LocationConverter : CpgCompositeConverter<PhysicalLocation?> {
     override fun toGraphProperties(value: PhysicalLocation?): Map<String, *> {
         val properties: MutableMap<String, Any> = HashMap()
         if (value != null) {
@@ -47,6 +56,16 @@ class LocationConverter : CompositeAttributeConverter<PhysicalLocation?> {
         return properties
     }
 
+    override val graphSchema: List<Pair<String, String>>
+        get() =
+            listOf(
+                Pair("String", ARTIFACT),
+                Pair("int", START_LINE),
+                Pair("int", END_LINE),
+                Pair("int", START_COLUMN),
+                Pair("int", END_COLUMN)
+            )
+
     override fun toEntityAttribute(value: Map<String, *>?): PhysicalLocation? {
         return try {
             val startLine = toInt(value?.get(START_LINE)) ?: return null

cpg-core/src/main/kotlin/de/fraunhofer/aisec/cpg/helpers/neo4j/NameConverter.kt

@@ -27,7 +27,6 @@ package de.fraunhofer.aisec.cpg.helpers.neo4j
 
 import de.fraunhofer.aisec.cpg.graph.Name
 import de.fraunhofer.aisec.cpg.graph.parseName
-import org.neo4j.ogm.typeconversion.CompositeAttributeConverter
 
 /**
  * This converter can be used in a Neo4J session to persist the [Name] class into its components:
@@ -37,7 +36,7 @@ import org.neo4j.ogm.typeconversion.CompositeAttributeConverter
  *
  * Additionally, it converts the aforementioned Neo4J attributes in a node back into a [Name].
  */
-class NameConverter : CompositeAttributeConverter<Name?> {
+class NameConverter : CpgCompositeConverter<Name?> {
 
     companion object {
         const val FIELD_FULL_NAME = "fullName"
@@ -61,14 +60,22 @@ class NameConverter : CompositeAttributeConverter<Name?> {
 
             // For reasons such as backwards compatibility and the fact that Neo4J likes to display
             // nodes in the UI with a "name" field as default, we also persist the full name (aka
-            // the
-            // toString() representation) as "name"
+            // the toString() representation) as "name"
             map[FIELD_NAME] = value.toString()
         }
 
         return map
     }
 
+    override val graphSchema: List<Pair<String, String>>
+        get() =
+            listOf(
+                Pair("String", FIELD_FULL_NAME),
+                Pair("String", FIELD_LOCAL_NAME),
+                Pair("String", FIELD_NAME),
+                Pair("String", FIELD_NAME_DELIMITER)
+            )
+
     override fun toEntityAttribute(value: MutableMap<String, *>): Name {
         return parseName(value[FIELD_FULL_NAME].toString(), value[FIELD_NAME_DELIMITER].toString())
     }

cpg-neo4j/src/main/kotlin/de/fraunhofer/aisec/cpg_vis_neo4j/Application.kt

@@ -218,6 +218,18 @@ class Application : Callable<Int> {
     )
     private var inferNodes: Boolean = false
 
+    @CommandLine.Option(
+        names = ["--schema-markdown"],
+        description = ["Print the CPGs nodes and edges that they can have."]
+    )
+    private var schemaMarkdown: Boolean = false
+
+    @CommandLine.Option(
+        names = ["--schema-json"],
+        description = ["Print the CPGs nodes and edges that they can have."]
+    )
+    private var schemaJson: Boolean = false
+
     @CommandLine.Option(
         names = ["--top-level"],
         description =
@@ -534,6 +546,12 @@ class Application : Callable<Int> {
         return translationConfiguration.build()
     }
 
+    public fun printSchema(filenames: Collection<String>, format: Schema.Format) {
+        val schema = Schema()
+        schema.extractSchema()
+        filenames.forEach { schema.printToFile(it, format) }
+    }
+
     /**
      * The entrypoint of the cpg-vis-neo4j.
      *
@@ -546,6 +564,17 @@ class Application : Callable<Int> {
      */
     @Throws(Exception::class, ConnectException::class, IllegalArgumentException::class)
     override fun call(): Int {
+
+        if (schemaMarkdown || schemaJson) {
+            if (schemaMarkdown) {
+                printSchema(mutuallyExclusiveParameters.files, Schema.Format.MARKDOWN)
+            }
+            if (schemaJson) {
+                printSchema(mutuallyExclusiveParameters.files, Schema.Format.JSON)
+            }
+            return EXIT_SUCCESS
+        }
+
         if (mutuallyExclusiveParameters.listPasses) {
             log.info("List of passes:")
             passList.iterator().forEach { log.info("- $it") }