From 1a447ca51a657e3c320e9ec6cfc13ec6fb779226 Mon Sep 17 00:00:00 2001 From: "A.Arnold" Date: Fri, 14 Mar 2025 14:29:09 +0000 Subject: [PATCH 1/5] MTA-4775: Effort differs between applications depending on whether they can be built or not Signed-off-by: A.Arnold --- docs/topics/create-yaml-rule.adoc | 2 +- docs/topics/yaml-rule-structure-syntax.adoc | 178 ++++++++++++++++---- 2 files changed, 144 insertions(+), 36 deletions(-) diff --git a/docs/topics/create-yaml-rule.adoc b/docs/topics/create-yaml-rule.adoc index b1598560..c852d9b0 100644 --- a/docs/topics/create-yaml-rule.adoc +++ b/docs/topics/create-yaml-rule.adoc @@ -173,7 +173,7 @@ _Example_ when: java.referenced: location: PACKAGE - pattern: org.jboss.* + pattern: org.jboss* ---- . Create an `AND` or `OR` condition diff --git a/docs/topics/yaml-rule-structure-syntax.adoc b/docs/topics/yaml-rule-structure-syntax.adoc index 695f95c0..32611f31 100644 --- a/docs/topics/yaml-rule-structure-syntax.adoc +++ b/docs/topics/yaml-rule-structure-syntax.adoc @@ -228,7 +228,8 @@ when: {ProductShortName} supports three types of conditions: `provider`, `and`, and `or`. -==== Provider conditions +[id="yaml-provider-conditions_{context}"] +== Provider conditions The Application Analyzer detects the programming languages, frameworks, and tools used to build an application, and it generates default rulesets for each supported provider using the Language Server Protocol (LSP) accordingly. Each supported provider has a ruleset defined by default and is run independently in a separate container. @@ -273,7 +274,8 @@ a| * Node.js |=== -===== `builtin` provider +[id="yaml-builtin-provider_{context}"] +=== `builtin` provider `builtin` is an internal provider that can analyze various files and internal metadata generated by the engine. @@ -350,15 +352,19 @@ when: ---- <1> When more than one tag is given, a logical AND is implied. -===== `java` provider +[id="yaml-java-provider_{context}"] +=== `java` provider -The `java` provider analyzes Java source code. +The Language Server used by the Java provider is Eclipse’s JDT Language Server (JDTLS). Internally, the JDTLS uses the Eclipse Java Development Toolkit, which includes utilities for searching code in projects. This provider has the following capabilities: * `referenced` * `dependency` +In the `pattern` element of a `java.referenced` condition, you can search through application code by using these utilities. For more details, see link:https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fsearch%2FSearchPattern.html&anchor=createPattern[Class SearchPattern], which contains all the information for building these patterns for `createPattern(String, int, int, int)`. + + .`referenced` The `referenced` capability enables the provider to find references in the source code. This capability takes three input parameters: `pattern`, `location`, and `annotated`. @@ -371,49 +377,151 @@ when: location: "" <2> annotated: "" <3> ---- -<1> A regular expression pattern to match, for example, `org.kubernetes.*`. +<1> A regular expression pattern to match, for example, `org.kubernetes*`. <2> Specifies the exact location where the pattern needs to be matched, for example, `IMPORT`. <3> Checks for specific annotations and their elements, such as name and value in the Java code using a query. For example, the following query matches the Bean(url = “http://www.example.com”) annotation in the method. + + +.Examples + +* Search for any class under the `javax.xml` package, occurring in any +location: + -[source,terminal] +[source,yaml] ---- - annotated: - pattern: org.framework.Bean - elements: - - name: url - value: "http://www.example.com" +java.referenced: + pattern: javax.xml* ---- ++ +[WARNING] +==== +If you want to match using an asterisk `*` wildcard for a wider range of results, it is recommended to place it directly after the package, not after the dot: -The supported locations are the following: +For example: -* `CONSTRUCTOR_CALL` -* `TYPE` -* `INHERITANCE` -* `METHOD_CALL` -* `ANNOTATION` -* `IMPLEMENTS_TYPE` -* `ENUM_CONSTANT` -* `RETURN_TYPE` -* `IMPORT` -* `VARIABLE_DECLARATION` -* `FIELD` -* `METHOD` +* `pattern: javax.xml*` ++ +and not: -.`dependency` +* `pattern: javax.xml.*` +==== -The `dependency` capability enables the provider to find dependencies for a given application. {ProductShortName} generates a list of the application's dependencies, and you can use this capability to query the list and check whether a certain dependency exists for the application within a given range of the dependency's versions. +* Search for method declarations that return `java.lang.String`: ++ +[source,yaml] +---- +java.referenced: + location: METHOD + pattern: '* java.lang.String' +---- -[source,terminal] +* Search for a method named "`method`" declared on `org.konveyor.MyClass` +that returns a `List` of a type that extends `java.lang.String`: ++ +[source,yaml] ---- -when: - java.dependency: - name: "" <1> - upperbound: "" <2> - lowerbound: "" <3> +java.referenced: + location: METHOD + pattern: 'org.konveyor.Myclass.method(*) java.util.List' ---- -<1> Name of the dependency to search for. -<2> Upper bound on the version of the dependency. -<3> Lower bound on the version of the dependency. + +* Search for a class that implements `java.util.List`: ++ +[source,yaml] +---- +java.referenced: + location: IMPLEMENTS_TYPE + pattern: java.util.List +---- + +[id="yaml-java-locations_{context}"] +==== `java` locations + +The Java provider allows scoping down the search to certain source code locations. You can scope down Java searches from any one of the following search locations: + +* *IMPORT*: IMPORT allows for searches on class imports. It can either be used with a fully qualified domain name (FQDN) or an asterisk as a wildcard to allow for wider matches: ++ +For example: ++ +[source,yaml] +---- +java.referenced: + pattern: org.apache.lucene.search* + location: IMPORT +---- + ++ +This scope would match on each of these imports: ++ +[source,java] +---- +import org.apache.lucene.search.Query; +import org.apache.lucene.search.Sort; +import org.apache.lucene.search.SortField; +---- ++ +If you want to match using an asterisk `*` wildcard for a wider range of results, it is recommended to place it directly after the package, not after the dot: + +** Use: `org.apache.lucene.search*` + +** Do not use: `org.apache.lucene.search.*` + + +* *PACKAGE*: PACKAGE allows for searches on any usage of a package, be it in an import or used as part of a FQDN in the code: ++ +[source,yaml] +---- +java.referenced: + pattern: org.apache.lucene.search* + location: PACKAGE +---- ++ +This scope would match on both the import and the fully qualified usage: ++ +[source,java] +---- +import org.apache.lucene.search.*; +---- ++ +[source,java] +---- +public class Test { + private org.apache.lucene.search.Query query; +} +---- ++ +If you want to match using an asterisk `*` wildcard for a wider range of results, it is recommended to place it directly after the package, not after the dot. + + +* *CONSTRUCTOR_CALL* and *METHOD_CALL*: for matching constructors and methods, respectively. The pattern possibilities are varied, and it is possible to match against specific return types, arguments, and so on. ++ +For instance, looking for a method named `method` declared in the `org.konveyor.MyClass` that returns a `List` of a type that extends `java.lang.String` and accepts a single parameter: ++ +[source,yaml] +---- +java.referenced: + location: METHOD + pattern: 'org.konveyor.Myclass.method(*) java.util.List' +---- + +More information about the possibilities of these patterns can be found in the link:[Class SearchPattern section] of the Eclipse documentation, which contain all the required information for building these patterns. + +[WARNING] +==== +In the current release of {ProductShortName}, fully qualified static method matching does not function as expected. +==== + +* *TYPE*: matches against types in general, appearing anywhere. +* *INHERITANCE*: matches against a class inheriting from a given type. +* *ANNOTATION*: matches against annotations. +* *IMPLEMENTS_TYPE*: matches against any type implementing the given type. +* *ENUM_CONSTANT*: matches against `enum` constants. +* *RETURN_TYPE*: matches against a type being returned by a method. +* *VARIABLE_DECLARATION*: matches against a type being declared as a variable. +* *FIELD* (declaration): matches against a type appearing in a field declaration. It can be coupled with an annotation match, this being an annotation happening on the field. +* *METHOD*: matches against a given method declaration. It can be coupled with an annotation match. +* *CLASS* (declaration): matches against a given method declaration. It can be coupled with an annotation match. + ===== `go` provider From 3d765c8f0e91cfb2eb91d2c5a53ebabc136f66c0 Mon Sep 17 00:00:00 2001 From: "A.Arnold" Date: Thu, 20 Mar 2025 23:01:35 +0000 Subject: [PATCH 2/5] add Signed-off-by: A.Arnold --- docs/topics/yaml-rule-structure-syntax.adoc | 59 +++++++++++++++------ 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/docs/topics/yaml-rule-structure-syntax.adoc b/docs/topics/yaml-rule-structure-syntax.adoc index 32611f31..9bf2cdab 100644 --- a/docs/topics/yaml-rule-structure-syntax.adoc +++ b/docs/topics/yaml-rule-structure-syntax.adoc @@ -353,7 +353,7 @@ when: <1> When more than one tag is given, a logical AND is implied. [id="yaml-java-provider_{context}"] -=== `java` provider +== `java` provider The Language Server used by the Java provider is Eclipse’s JDT Language Server (JDTLS). Internally, the JDTLS uses the Eclipse Java Development Toolkit, which includes utilities for searching code in projects. @@ -364,8 +364,8 @@ This provider has the following capabilities: In the `pattern` element of a `java.referenced` condition, you can search through application code by using these utilities. For more details, see link:https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fsearch%2FSearchPattern.html&anchor=createPattern[Class SearchPattern], which contains all the information for building these patterns for `createPattern(String, int, int, int)`. - -.`referenced` +[id="yaml-java-referenced_{context}"] +=== `referenced` The `referenced` capability enables the provider to find references in the source code. This capability takes three input parameters: `pattern`, `location`, and `annotated`. @@ -380,7 +380,15 @@ when: <1> A regular expression pattern to match, for example, `org.kubernetes*`. <2> Specifies the exact location where the pattern needs to be matched, for example, `IMPORT`. <3> Checks for specific annotations and their elements, such as name and value in the Java code using a query. For example, the following query matches the Bean(url = “http://www.example.com”) annotation in the method. - ++ +[source,terminal] +---- + annotated: + pattern: org.framework.Bean + elements: + - name: url + value: "http://www.example.com" +---- .Examples @@ -434,8 +442,25 @@ java.referenced: pattern: java.util.List ---- +[id="yaml-java-dependency_{context}"] +=== `dependency` + +The `dependency` capability enables the provider to find dependencies for a given application. {ProductShortName} generates a list of the application's dependencies, and you can use this capability to query the list and check whether a certain dependency exists for the application within a given range of the dependency's versions. + +[source,terminal] +---- +when: + java.dependency: + name: "" <1> + upperbound: "" <2> + lowerbound: "" <3> +---- +<1> Name of the dependency to search for. +<2> Upper bound on the version of the dependency. +<3> Lower bound on the version of the dependency. + [id="yaml-java-locations_{context}"] -==== `java` locations +=== `java` locations The Java provider allows scoping down the search to certain source code locations. You can scope down Java searches from any one of the following search locations: @@ -466,7 +491,6 @@ If you want to match using an asterisk `*` wildcard for a wider range of results ** Do not use: `org.apache.lucene.search.*` - * *PACKAGE*: PACKAGE allows for searches on any usage of a package, be it in an import or used as part of a FQDN in the code: + [source,yaml] @@ -515,15 +539,15 @@ In the current release of {ProductShortName}, fully qualified static method matc * *INHERITANCE*: matches against a class inheriting from a given type. * *ANNOTATION*: matches against annotations. * *IMPLEMENTS_TYPE*: matches against any type implementing the given type. -* *ENUM_CONSTANT*: matches against `enum` constants. +* *ENUM_CONSTANT*: matches against enum constants. * *RETURN_TYPE*: matches against a type being returned by a method. * *VARIABLE_DECLARATION*: matches against a type being declared as a variable. * *FIELD* (declaration): matches against a type appearing in a field declaration. It can be coupled with an annotation match, this being an annotation happening on the field. * *METHOD*: matches against a given method declaration. It can be coupled with an annotation match. * *CLASS* (declaration): matches against a given method declaration. It can be coupled with an annotation match. - -===== `go` provider +[id="yaml-go-provider_{context}"] +== `go` provider The `go` provider analyzes Go source code. This provider's capabilities are `referenced` and `dependency`. @@ -553,7 +577,8 @@ when: <2> Upper bound on the version of the dependency. <3> Lower bound on the version of the dependency. -===== `dotnet` provider +[id="yaml-dotnet-provider_{context}"] +== `dotnet` provider The `dotnet` is an external provider used to analyze .NET and C# source code. Currently, the provider supports the `referenced` capability. @@ -571,7 +596,8 @@ when: <1> `pattern`: A regex pattern to match the desired reference. For example, HttpNotFound. <2> `namespace`: Specifies the namespace to search within. For example, System.Web.Mvc. -==== Custom variables +[id="yaml-custom-variables_{context}"] +== Custom variables Provider conditions can have associated custom variables. You can use custom variables to capture relevant information from the matched line in the source code. The values of these variables are interpolated with data matched in the source code. These values can be used to generate detailed templated messages in a rule's action (see xref:yaml-rule-actions_{context}[Message actions]). They can be added to a rule in the `customVariables` field: @@ -592,12 +618,13 @@ Provider conditions can have associated custom variables. You can use custom var <2> `name`: The name of the variable that can be used in templates. <3> `message`: A template for a message using a custom variable. - -=== Logical conditions +[id="yaml-logical-conditions_{context}"] +== Logical conditions The analyzer provides two basic logical conditions, `and` and `or`, which enable you to aggregate results of other conditions and create more complex queries. -==== `and` condition +[id="yaml-logical-and_{context}"] +=== `and` condition The `and` condition performs a logical AND operation on the results of an array of conditions. An `and` condition matches when _all_ of its child conditions match. @@ -640,7 +667,8 @@ when: - go.referenced: "*CustomResourceDefinition*" ---- -==== `or` condition +[id="yaml-logical-or_{context}"] +=== `or` condition The `or` condition performs a logical OR operation on the results of an array of conditions. An `or` condition matches when _any_ of its child conditions matches. @@ -667,6 +695,7 @@ when: pattern: junit.junit ---- +[id="yaml-rulesets_{context}"] == Rulesets A set of rules forms a ruleset. {ProductShortName} does not require every rule file to belong to a ruleset, but you can use rulesets to group multiple rules that achieve a common goal and to pass the rules to the rules engine. From f3030e11fc4569fceb6d5b1cec7bc59a74937481 Mon Sep 17 00:00:00 2001 From: Andy Arnold Date: Fri, 21 Mar 2025 10:09:46 +0000 Subject: [PATCH 3/5] Update docs/topics/yaml-rule-structure-syntax.adoc --- docs/topics/yaml-rule-structure-syntax.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/yaml-rule-structure-syntax.adoc b/docs/topics/yaml-rule-structure-syntax.adoc index 9bf2cdab..5cec03cd 100644 --- a/docs/topics/yaml-rule-structure-syntax.adoc +++ b/docs/topics/yaml-rule-structure-syntax.adoc @@ -539,7 +539,7 @@ In the current release of {ProductShortName}, fully qualified static method matc * *INHERITANCE*: matches against a class inheriting from a given type. * *ANNOTATION*: matches against annotations. * *IMPLEMENTS_TYPE*: matches against any type implementing the given type. -* *ENUM_CONSTANT*: matches against enum constants. +* *ENUM_CONSTANT*: matches against `enum` constants. * *RETURN_TYPE*: matches against a type being returned by a method. * *VARIABLE_DECLARATION*: matches against a type being declared as a variable. * *FIELD* (declaration): matches against a type appearing in a field declaration. It can be coupled with an annotation match, this being an annotation happening on the field. From 85ad74aae5e710f0c8946e080f84cff226c6744c Mon Sep 17 00:00:00 2001 From: Andy Arnold Date: Fri, 21 Mar 2025 12:04:01 +0000 Subject: [PATCH 4/5] Update docs/topics/yaml-rule-structure-syntax.adoc --- docs/topics/yaml-rule-structure-syntax.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/yaml-rule-structure-syntax.adoc b/docs/topics/yaml-rule-structure-syntax.adoc index 5cec03cd..3b6eedc2 100644 --- a/docs/topics/yaml-rule-structure-syntax.adoc +++ b/docs/topics/yaml-rule-structure-syntax.adoc @@ -593,7 +593,7 @@ when: pattern: "" <1> namespace: "" <2> ---- -<1> `pattern`: A regex pattern to match the desired reference. For example, HttpNotFound. +<1> `pattern`: A regular expression pattern to match the desired reference. For example, `HttpNotFound`. <2> `namespace`: Specifies the namespace to search within. For example, System.Web.Mvc. [id="yaml-custom-variables_{context}"] From 6eee14b0cbdb6298ef269bcc48caae1fab5b4960 Mon Sep 17 00:00:00 2001 From: Andy Arnold Date: Fri, 21 Mar 2025 12:48:54 +0000 Subject: [PATCH 5/5] Update docs/topics/yaml-rule-structure-syntax.adoc --- docs/topics/yaml-rule-structure-syntax.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/yaml-rule-structure-syntax.adoc b/docs/topics/yaml-rule-structure-syntax.adoc index 3b6eedc2..03ce76c4 100644 --- a/docs/topics/yaml-rule-structure-syntax.adoc +++ b/docs/topics/yaml-rule-structure-syntax.adoc @@ -594,7 +594,7 @@ when: namespace: "" <2> ---- <1> `pattern`: A regular expression pattern to match the desired reference. For example, `HttpNotFound`. -<2> `namespace`: Specifies the namespace to search within. For example, System.Web.Mvc. +<2> `namespace`: Specifies the namespace to search within. For example, `System.Web.Mvc`. [id="yaml-custom-variables_{context}"] == Custom variables