Skip to content

Commit 859bc95

Browse files
raoradhikaraoradhika
authored
Merge pull request #92 from anarnold97/MTA-4637-Pattern-matching-docs-need-urgent-improvements
WIP - MTA-4637: Pattern matching docs need urgent improvements
2 parents 5a9999d + 057fad1 commit 859bc95

25 files changed

+1287
-560
lines changed

‎docs/rules-development-guide/master.adoc

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,17 +31,68 @@ include::topics/about-rules.adoc[leveloffset=+2]
3131

3232
Each analyzer rule is a set of instructions that are used to analyze source code and detect issues that are problematic for migration.
3333

34-
The analyzer parses user-provided rules, applies them to applications' source code, and generates issues for matched rules. A collection of one or more rules forms a ruleset. Creating rulesets provides a way of organizing multiple rules that achieve a common goal. The analyzer CLI takes rulesets as input arguments.
34+
The analyzer parses user-provided rules, applies them to applications' source code, and generates issues for matched rules.
35+
36+
A collection of one or more rules forms a ruleset. Creating rulesets provides a way of organizing multiple rules that achieve a common goal.
37+
38+
The analyzer CLI takes rulesets as input arguments.
39+
3540

3641
include::topics/yaml-rule-structure-syntax.adoc[leveloffset=+2]
3742

43+
include::topics/yaml-rule-labels.adoc[leveloffset=+2]
44+
3845
[id="creating-basic-yaml-rules_{context}"]
3946
=== Creating a basic YAML rule
4047

4148
This section describes how to create a basic {ProductShortName} YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions.
4249

4350
include::topics/create-basic-yaml-rule-template.adoc[leveloffset=+3]
4451

52+
include::topics/yaml-rule-categories.adoc[leveloffset=+3]
53+
54+
include::topics/yaml-rule-actions.adoc[leveloffset=+3]
55+
56+
include::topics/yaml-rule-conditions.adoc[leveloffset=+3]
57+
58+
include::topics/yaml-tag-actions.adoc[leveloffset=+3]
59+
60+
include::topics/yaml-message-actions.adoc[leveloffset=+3]
61+
62+
include::topics/yaml-rule-hyperlinks.adoc[leveloffset=+3]
63+
64+
include::topics/yaml-provider-conditions.adoc[leveloffset=+3]
65+
66+
include::topics/yaml-builin-provider.adoc[leveloffset=+4]
67+
68+
include::topics/yaml-java-provider.adoc[leveloffset=+4]
69+
70+
include::topics/yaml-java-locations.adoc[leveloffset=+4]
71+
72+
include::topics/yaml-annotation-inspection.adoc[leveloffset=+4]
73+
74+
include::topics/yaml-go-provider.adoc[leveloffset=+4]
75+
76+
include::topics/yaml-dotnet-provider.adoc[leveloffset=+4]
77+
78+
include::topics/yaml-condition-patterns.adoc[leveloffset=+3]
79+
80+
include::topics/yaml-custom-variables.adoc[leveloffset=+3]
81+
82+
include::topics/yaml-logical-conditions.adoc[leveloffset=+3]
83+
84+
include::topics/yaml-and-condition.adoc[leveloffset=+4]
85+
86+
include::topics/yaml-or-condition.adoc[leveloffset=+4]
87+
88+
include::topics/yaml-chaining-condition-variables.adoc[leveloffset=+4]
89+
90+
include::topics/yaml-chaining-java-provider.adoc[leveloffset=+5]
91+
92+
include::topics/yaml-rulesets.adoc[leveloffset=+3]
93+
94+
95+
4596
include::topics/create-basic-yaml-ruleset-template.adoc[leveloffset=+3]
4697

4798
include::topics/create-yaml-rule.adoc[leveloffset=+3]

‎docs/topics/create-yaml-rule.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ _Example_
173173
when:
174174
java.referenced:
175175
location: PACKAGE
176-
pattern: org.jboss.*
176+
pattern: org.jboss*
177177
----
178178

179179
. Create an `AND` or `OR` condition

‎docs/topics/yaml-and-condition.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * docs/rules-development-guide/master.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="yaml-and-condition_{context}"]
7+
= AND condition
8+
9+
The `and` condition performs a logical AND operation on the results of an array of conditions.
10+
11+
The `and` condition matches when _all_ of its child conditions match, for example:
12+
13+
[source,yaml]
14+
----
15+
when:
16+
and:
17+
- <condition1>
18+
- <condition2>
19+
----
20+
21+
.Example
22+
23+
[source,yaml]
24+
----
25+
when:
26+
and:
27+
- java.dependency:
28+
name: junit.junit
29+
upperbound: 4.12.2
30+
lowerbound: 4.4.0
31+
- java.referenced:
32+
location: IMPORT
33+
pattern: junit.junit
34+
----
35+
36+
[id="yaml-nested-and-condition_{context}"]
37+
== Nested conditions
38+
Conditions can also be nested within other conditions.
39+
40+
. Example
41+
42+
[source,yaml]
43+
----
44+
when:
45+
and:
46+
- and:
47+
- go.referenced: "*CustomResourceDefinition*"
48+
- java.referenced:
49+
pattern: "*CustomResourceDefinition*"
50+
- go.referenced: "*CustomResourceDefinition*"
51+
----

‎docs/topics/yaml-annotation-inspection.adoc

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * docs/rules-development-guide/master.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="yaml-annotation-inspection_{context}"]
7+
= Annotation inspection
8+
9+
You can add a query to match against specific annotations and their elements, for example:
10+
11+
[source,yaml]
12+
----
13+
when:
14+
java.referenced:
15+
location: METHOD
16+
pattern: org.package.MyApplication.runApplication(java.lang.String)
17+
annotated:
18+
pattern: org.framework.Bean
19+
elements:
20+
- name: url
21+
value: "http://www.example.com"
22+
----
23+
24+
This would match against the `runApplication` method in the following Java code:
25+
26+
[source,java]
27+
----
28+
package org.package
29+
30+
import org.framework.Bean;
31+
32+
class MyApplication {
33+
34+
@Bean(url = "http://www.example.com")
35+
public String runApplication(String str) {
36+
// ...
37+
}
38+
}
39+
----
40+
41+
The structure of the `annotated` YAML element is:
42+
43+
[source,yaml]
44+
----
45+
annotated:
46+
pattern: a Java regex to match the fully qualified name of the annotation (optional)
47+
elements: an array of elements to match within the annotation (optional)
48+
- name: the exact name of the element to match against
49+
value: a Java regex to match the value of the element
50+
----
51+
52+
It is also possible to match an annotation with specific elements, without having to specify the symbol it annotates. The following example would also match on the `@Bean` annotation in the same code as the previous example:
53+
54+
[source,yaml]
55+
----
56+
when:
57+
java.referenced:
58+
location: ANNOTATION
59+
pattern: org.framework.Bean
60+
annotated:
61+
elements:
62+
- name: url
63+
value: "http://www.example.com"
64+
----
65+
[NOTE]
66+
====
67+
The only element specified with a `pattern` is the annotation itself.
68+
====

‎docs/topics/yaml-builin-provider.adoc

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * docs/rules-development-guide/master.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="yaml-builin-provider_{context}"]
7+
= Builtin provider
8+
9+
The `builtin` is an internal provider that can analyze various files and internal metadata generated by the engine. This provider has the following capabilities:
10+
11+
* `file`
12+
* `filecontent`
13+
* `xml`
14+
* `json`
15+
* `hasTags`
16+
17+
.`file`
18+
19+
By using the `file` capability, the provider searches for files in the source code that match a given pattern.
20+
21+
[source,yaml]
22+
----
23+
when:
24+
builtin.file:
25+
pattern: "<regex_to_match_filenames>"
26+
----
27+
28+
.`filecontent`
29+
30+
By using the `filecontent` capability, the provider searches for content that matches a given pattern.
31+
32+
[source,yaml]
33+
----
34+
when:
35+
builtin.filecontent:
36+
filePattern: "<regex_to_match_filenames_to_scope_search>"
37+
pattern: "<regex_to_match_content_in_the_matching_files>"
38+
----
39+
40+
.`xml`
41+
42+
The `xml` capability enables the provider to query XPath expressions on a list of provided XML files. This capability takes 2 input parameters, `xpath` and `filepaths`.
43+
44+
[source,yaml]
45+
----
46+
when:
47+
builtin.xml:
48+
xpath: "<xpath_expressions>" # <1>
49+
filepaths: # <2>
50+
- "/src/file1.xml"
51+
- "/src/file2.xml"
52+
----
53+
<1> `xpath` must be a valid XPath expression.
54+
<2> `filepaths` is a list of files to apply the XPath query to.
55+
56+
.`json`
57+
58+
By using the `json` capability, the provider queries XPath expressions on a list of provided JSON files. Currently, `json` only takes XPath as input and performs the search on all JSON files in the codebase.
59+
60+
[source,yaml]
61+
----
62+
when:
63+
builtin.json:
64+
xpath: "<xpath_expressions>" # <1>
65+
----
66+
<1> `xpath` must be a valid XPath expression.
67+
68+
.`hasTags`
69+
70+
By using the `hasTags` capability, the provider queries application tags. It queries the internal data structure to check whether the application has the given tags.
71+
72+
[source,yaml]
73+
----
74+
when:
75+
# when more than one tag is given, a logical AND is implied
76+
hasTags: #<1>
77+
- "tag1"
78+
- "tag2"
79+
----
80+
<1> When more than one tag is given, a logical AND is implied.

‎docs/topics/yaml-chaining-condition-variables.adoc

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * docs/rules-development-guide/master.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="yaml-chaining-condition-variables_{context}"]
7+
= Chaining Condition Variables
8+
9+
You can use the output of one condition as the input for filtering another one in the `and` and `or` conditions. This is called *condition chaining*.
10+
11+
12+
.Example
13+
14+
[source,yaml]
15+
----
16+
when:
17+
or:
18+
- builtin.xml:
19+
xpath: "//dependencies/dependency"
20+
filepaths: "{{poms.filepaths}}"
21+
from: poms
22+
- builtin.file:
23+
pattern: pom.xml
24+
as: poms
25+
ignore: true
26+
----
27+
28+
In the above example, the output of the `builtin.file` condition is saved as `poms`:
29+
30+
+
31+
[source,yaml]
32+
----
33+
[...]
34+
as: poms
35+
[...]
36+
----
37+
38+
The variables of `builtin.file` can then be used in the `builtin.xml` condition, by writing `from` and then using link:https://mustache.github.io/mustache.5.html[mustache templates] in the `provider_ condition` block.
39+
40+
This is how this particular condition knows how to use the variable set to the name `poms`.
41+
42+
+
43+
[source,yaml]
44+
----
45+
[...]
46+
from: poms
47+
[...]
48+
----
49+
50+
Then you can use the variables by setting them as mustached templates in
51+
any of the inputs to the _provider_ condition.
52+
53+
+
54+
[source,yaml]
55+
----
56+
[...]
57+
filepaths: "{{poms.filepaths}}"
58+
[...]
59+
----
60+
61+
[NOTE]
62+
====
63+
If you only want to use the values of a condition as a chain, you can set `ignore: true`.
64+
65+
This will tell the engine not to use this condition to determine whether the rule has been violated or not:
66+
+
67+
[source,yaml]
68+
----
69+
[...]
70+
ignore: true
71+
[...]
72+
----
73+
====

‎docs/topics/yaml-chaining-java-provider.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * docs/rules-development-guide/master.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="yaml-chaining-java-provider_{context}"]
7+
= Chaining in the Java provider
8+
9+
In the `java` provider, the `filepaths` variable must be uppercased. for example:
10+
11+
[source,yaml]
12+
----
13+
when:
14+
and:
15+
- java.referenced:
16+
pattern: org.springframework.web.bind.annotation.RequestMapping
17+
location: ANNOTATION
18+
as: annotation
19+
- java.referenced:
20+
pattern: org.springframework.stereotype.Controller
21+
location: ANNOTATION
22+
filepaths: "{{annotation.Filepaths}}"
23+
----

0 commit comments

Comments
 (0)