Chapter 2. Creating YAML rules

Procedure

1. In the /home/<USER>/ directory, create a file containing the basic syntax for YAML rules as follows:

   - category: mandatory
     description: |
      <DESCRIPTION TITLE>
      <DESCRIPTION TEXT>
     effort: <EFFORT>
     labels:
     - konveyor.io/source=<SOURCE_TECH>
     - konveyor.io/target=<TARGET_TECH>
     links:
    - url: <HYPERLINK>
      title: <HYPERLINK_TITLE>
     message: <MESSAGE>
     tag:
     - <TAG1>
     - <TAG2>
     ruleID: <RULE_ID>
     when:
      <CONDITIONS>

Procedure

1. Create a template for ruleset.yaml files if you want to pass the entire directory using the --rules option:

   name: <RULESET_NAME> 1
   description: <RULESET_DESCRIPTION>
   labels: 2
     - key=val

   1

   The name must be unique within the provided rulesets.

   2

   Ruleset labels are inherited by all rules that belong to the ruleset.

Procedure

1. Create a when condition.

   The when condition of a YAML rule can be provider, and or or.

   1. Create a provider condition

      The provider condition is used to define a search query for a specific language provider and to invoke a certain capability of the provider.

      The condition’s general format is <provider_name>.<capability>. The condition also has inner fields to specify details of the search. The way you create a provider condition and its inner fields depends on which provider you use and which capability you invoke.

      The table below lists the available providers and their capabilities. Select a provider and its capability that suit the purpose of the rule you want to create. This part of the condition does not contain any of the condition’s fields yet.

      Provider	Capability	Description
      java	referenced	Finds references of a pattern, including annotations, with an optional code location for detailed searches
      	dependency	Checks whether the application has a given dependency
      builtin	xml	Searches XML files using XPath queries
      	json	Searches JSON files using JSONPath queries
      	filecontent	Searches content in regular files using RegEx patterns
      	file	Finds files with names matching a given pattern
      	hasTags	Checks whether a tag is created for the application through a tagging rule
      go	referenced	Finds references of a pattern
      	dependency	Checks whether the application has a given dependency

      The example below shows a java provider condition that uses the referenced capability.

      Example

      when:
        java.referenced:

2. Add suitable fields to the provider condition.

   The table below lists all available providers, their capabilities, and their fields. Select the fields that belong to the provider and capability that you have chosen. Note that some fields are mandatory.

   Provider	Capability	Field	Required?	Description
   java	referenced	pattern	Yes	RegEx pattern
   		location	No	Source code location; see below for a list of all supported search locations
   		annotated	No	Annotations and their elements (name and value)
   	dependency	name	Yes	Name of the dependency
   		nameregex	No	RegEx pattern to match the name
   		upperbound	No	Matches version numbers lower than or equal to
   		lowerbound	No	Matches version numbers greater than or equal to
   builtin	xml	xpath	Yes	XPath query
   		namespaces	No	A map to scope down query to namespaces
   		filepaths	No	Optional list of files to scope down search
   	json	xpath	Yes	XPath query
   		filepaths	No	Optional list of files to scope down search
   	filecontent	pattern	Yes	RegEx pattern to match in content
   		filePattern	No	Only searches in files with names matching this pattern
   	file	pattern	Yes	Finds files with names matching this pattern
   	hasTags	This is an inline list of string tags. See Tag Actions in Rule Actions for details on tag format.
   go	referenced	pattern	Yes	RegEx pattern
   	dependency	name	Yes	Name of the dependency
   		nameregex	No	RegEx pattern to match the name
   		upperbound	No	Matches version numbers lower than or equal to
   		lowerbound	No	Matches version numbers greater than or equal to

   The following search locations can be used to scope down java searches:

   • CONSTRUCTOR_CALL
   • TYPE
   • INHERITANCE
   • METHOD_CALL
   • ANNOTATION
   • IMPLEMENTS_TYPE
   • ENUM_CONSTANT
   • RETURN_TYPE
   • IMPORT

   • VARIABLE_DECLARATION

     The example below shows the when condition of a rule that searches for references of a package.

     Example

     when:
       java.referenced:
         location: PACKAGE
         pattern: org.jboss.*

3. Create an AND or OR condition

   • An and condition matches when all of its child conditions match. Create an and condition as follows:

     when:
       and:
       - java.dependency:
           name: junit.junit
           upperbound: 4.12.2
           lowerbound: 4.4.0
       - java.referenced:
           location: IMPORT
           pattern: junit.junit

   • An or condition matches when any of its child conditions match. Create an or condition as follows:

     when:
       or:
       - java.dependency:
           name: junit.junit
           upperbound: 4.12.2
           lowerbound: 4.4.0
       - java.referenced:
           location: IMPORT
           pattern: junit.junit

1. Create jboss-web.xml and pom.xml files in a directory:

   mkdir /home/<USER>/data/
   touch /home/<USER>/data/jboss-web.xml
   touch /home/<USER>/data/pom.xml

2. In the jboss-web.xml file you created, paste the following content:

   <!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 4.2//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_4_2.dtd">
   <jboss-web>
       <class-loading java2ClassLoadingCompliance="false">
           <loader-repository>
               seam.jboss.org:loader=@projectName@
               <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
           </loader-repository>
       </class-loading>
   </jboss-web>

3. In the pom.xml file you created, paste the following content:

   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   
     <groupId>test</groupId>
     <artifactId>test</artifactId>
     <version>1.1.0-SNAPSHOT</version>
   
     <properties>
   	<maven.compiler.source>1.7</maven.compiler.source>
   	<maven.compiler.target>1.7</maven.compiler.target>
     </properties>
   
     <dependencies>
     </dependencies>
   </project>

Procedure

1. Once the analysis is complete, the command outputs the path to the HTML report:

   INFO[0066] Static report created. Access it at this URL:  URL="file:/home/<USER>/output/static-report/index.html"

   Open /home/<USER_NAME>/output/static-report/index.html in a web browser.

2. Navigate to the Issues tab in the left menu.

3. Verify that the rule is executed:

   1. In the Issues table, type JBoss XML in the search bar.
   2. Verify that the issue with the title Find class loading element in JBoss XML file is present in the table.
4. Click the jboss-web.xml link to open the affected file.