From 07499f56b32990652b59800953b94b8e5de37503 Mon Sep 17 00:00:00 2001 From: Markus Lottmann Date: Thu, 6 Jul 2023 13:02:26 +0200 Subject: [PATCH] Rework comments for some CPG properties. Added/adjuted comments for METHOD_FULL_NAME, TYPE_FULL_NAME, DYNAMIC_TYPE_HINT_FULL_NAME. --- .../codepropertygraph/schema/CallGraph.scala | 14 +++++++++++-- .../codepropertygraph/schema/Hidden.scala | 9 ++++++++- .../codepropertygraph/schema/Type.scala | 20 ++++++++++++++++--- 3 files changed, 37 insertions(+), 6 deletions(-) diff --git a/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/CallGraph.scala b/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/CallGraph.scala index fb0569bc0..57066f66c 100644 --- a/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/CallGraph.scala +++ b/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/CallGraph.scala @@ -55,8 +55,18 @@ object CallGraph extends SchemaBase { .addProperty( name = "METHOD_FULL_NAME", valueType = ValueType.String, - comment = """The FULL_NAME of a method. Used to link CALL and METHOD nodes. It is required - |to have exactly one METHOD node for each METHOD_FULL_NAME""".stripMargin + comment = """The FULL_NAME of a method. Used to link CALL and METHOD nodes. + |For METHOD nodes this property must be a unique fully-qualified name. + |For CALL nodes this property has different semantics depending on the + |CALL nodes DISPATCH_TYPE property. + |For DISPATCH_TYPE STATIC_DISPATCH this property contains the + |fully-qualified name of the called method. + |For DISPATCH_TYPE DYNAMIC_DISPATCH this property contains the + |fully-qualified name of the assured interface method which is + |straight forward for statically typed languages like Java and CSharp. + |For dynamically typed languages no interface assurance exists so + |frontends should indicate by some name like "". + |""".stripMargin ) .mandatory(PropertyDefaults.String) .protoId(54) diff --git a/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Hidden.scala b/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Hidden.scala index 7f04b4eb8..fef2c90df 100644 --- a/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Hidden.scala +++ b/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Hidden.scala @@ -155,7 +155,14 @@ object Hidden extends SchemaBase { .addProperty( name = "DYNAMIC_TYPE_HINT_FULL_NAME", valueType = ValueType.String, - comment = "Type hint for the dynamic type" + comment = """This is a multi valued property which gives information about all observable + |runtime types for the node carrying this property. This means if e.g. an + |expression has the static TYPE_FULL_NAME `SomeInterface` which is implemented + |by `ImplA`, `ImplB` and `ImplC` and DYNAMIC_TYPE_HINT_FULL_NAME is given as + |`List(ImplA, ImplB)`, that only `ImplA` and `ImplB` can ever be observed + |as runtime times and never `ImplC`. This property is used to enable shortcuts + |in data flow tracker implementations. + |""".stripMargin ) .asList() .protoId(1591) diff --git a/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Type.scala b/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Type.scala index 212e25422..80402fa35 100644 --- a/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Type.scala +++ b/schema/src/main/scala/io/shiftleft/codepropertygraph/schema/Type.scala @@ -31,9 +31,23 @@ object Type extends SchemaBase { name = "TYPE_FULL_NAME", valueType = ValueType.String, comment = """This field contains the fully-qualified static type name of the program - |construct represented by a node. It is the name of an instantiated type, e.g., - |`java.util.List`, rather than `java.util.List[T]`. If the type - |cannot be determined, this field should be set to the empty string. + |construct represented by a node. For static languages like Java and CSharp + |this property is supposed to be filled with type names guaranteed to be + |correct. E.g. type names coming from a compiler library or byte code. + |Dynamic languages have no static type information and are supposed + |to fill this property with always the same type name which indicates "any". + |This is why for example for Javascript the type name "ANY" is used. + |Type full names for higher kinded types like `java.util.List` can + |appear with or without a concrete types for `T`. Two examples for Java + |illustrate this: + | 1. `List l = null` + | Here the IDENTIFIER and LOCAL nodes for `l` have `java.lang.List` + | as type full name. + | 2. `class SomeGenericClass { void doStuff(List par1) { ... } }` + | Here the METHOD_PARAMETER_IN node for `par` has `java.lang.List` + | as type full name. + |If the type cannot be determined, use some indicative name reflecting this + |fact like "". |""".stripMargin ) .mandatory(PropertyDefaults.String)