The migration toolkit for applications (MTA) contains rule-based migration tools called analyzers that use pluggable providers to analyze static code, dependencies, and other files in your application.

Analyzers work with providers to detect issues that cause problems when you migrate the application to target technologies. The rule definition contains metadata description and condition patterns that describe a violation.

The analyzer runs a search query on the source code to match the violation described in the rule definition. The rule definition also contains a message that MTA displays when triggering an issue because of the violation. The analyzer uses default and user-provided (custom) rules during an analysis to identify issues.

A collection of one or more rules is called a ruleset. Creating rulesets provides a way of organizing multiple rules that analyze the source code for a specific target platform.

You can use rules or rulesets as input arguments in an analysis. You can perform a rule-based analysis in the MTA CLI, user interface, or by using one of the IDE plug-ins for MTA (Visual Studio Code or IntelliJ).

The rules can be used by Red Hat Developer Lightspeed for MTA to generate AI-assisted code resolutions. The issue description and metadata in rules are used by the Red Hat Developer Lightspeed for MTA to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that are identified through an analysis. See Configuring and Using Red Hat Developer Lightspeed for MTA for more information.

Rules instruct the analyzer to take the specified actions when the given conditions match. In MTA, a rule file contains one or more rules.

Rules are written in YAML. They consist of:

MTA analyzer rules have the following pattern:

ruleID:
labels:
category:
effort:
description:
when:
 <condition(s)>
message: "message"
tag:
 - tag_1, tag_2, tag_3
 - key_1="value_1, value_2"

Rule metadata contains a unique rule ID, labels, effort, and category.

ruleID: "unique_id"
labels:
  # key=value pair
  - "label1=val1"
  # valid label with value omitted
  - "label2"
  # valid label with empty value
  - "label3="
  # subdomain prefixed key
  - "konveyor.io/label1=val1"
effort: 1
category: mandatory

where:

Labels are key=val pairs specified in rules to filter the rule by the label. During an analysis, you can use the --label-selector option to apply the filter for rules or rulesets and the --dep-label-selector option to apply the filter for dependencies.

For dependencies, a provider adds the labels to the dependencies when retrieving them. Labels on a ruleset are automatically inherited by all the rules that belong to it.

labels:
- "key1=val1"
- "key2=val2"

The key of a label can be subdomain-prefixed:

labels:
- "konveyor.io/key1=val1"

The value of a label can be empty:

labels:
- "konveyor.io/key="

The value of a label can be omitted. In that case, it is treated as an empty value:

labels:
- "konveyor.io/key"

Examples:

Currently, the analyzer adds the following labels to dependencies:

labels:
- konveyor.io/dep-source=internal
- konveyor.io/language=java

For example, the analyzer adds a konveyor.io/dep-source label to dependencies with a value that indicates whether the dependency is a known open source dependency.

To exclude incidents for all such open source dependencies, you can use --dep-label-selector as follows:

$ mta-cli …​ --dep-label-selector !konveyor.io/dep-source=open-source

The Java provider in the analyzer can also add an exclude label to a list of packages. To exclude all such packages, you can use --dep-label-selector and the ! operator as follows:

konveyor-analyzer …​ --dep-label-selector !konveyor.io/exclude

mta-cli …​ --dep-label-selector !konveyor.io/exclude

Rule categories are applied per rule. The Architect assigns one of the following rule categories to indicate the risk associated with not resolving an issue.

The analyzer engine enables multi-language source code analysis by using providers. The source code of a technology is analyzed by the provider.

The provider publishes what they can do with the source code in terms of capabilities.

The provider condition instructs the analyzer to use a specific provider and one of its capabilities. In general, it follows the <provider_name>.<capability> pattern.

when:
  <provider_name>.<capability>
    <input_fields>

The analyzer currently supports the following provider conditions:

The following table summarizes all the providers and their capabilities:

when:
  java.referenced:
    <fields>

when:
  java.dependency:
    <fields>

when:
  builtin.json:
    <fields>

when:
  builtin.filecontent:
    <fields>

when:
  builtin.file:
    <fields>

when:
  builtin.hasTags:
    <fields>

when:
  go.referenced:
    <fields>

when:
  go.dependency:
    <fields>

Following the example in the previous table, you can create the first part of the condition that does not contain any of the condition fields.

when:
  java.referenced:
    <fields>

The following table summarizes available providers, their capabilities and all of their fields:

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

when:
  java.referenced:
    pattern: org.kubernetes*
    location: IMPORT

when:
  java.referenced:
    location: ANNOTATION
    pattern: javax.ejb.Singleton

when:
  java.dependency:
    name: junit.junit

when:
  java.dependency:
    name: junit.junit
    upperbound: 4.12.2

when:
  java.dependency:
    name: junit.junit
    upperbound: 4.12.2
    lowerbound: 4.4.0

when:
  builtin.xml:
    xpath: "//dependencies/dependency"

when:
  builtin.xml:
    filepaths:
     - beans.xml
    namespaces:
        b: http://xmlns.jcp.org/xml/ns/javaee
    xpath: /b:beans

when:
    or:
    - builtin.xml:
        xpath: "//dependencies/dependency"
        filepaths: "{{poms.filepaths}}"
      from: poms
    - builtin.file:
        pattern: pom.xml
      as: poms
      ignore: true

when:
    and:
    - builtin.json:
        xpath: //inclusionTestNode

when:
    and:
    - builtin.json:
        xpath: //inclusionTestNode
        filepaths: "{{incTest.filepaths}}"

when:
  builtin.filecontent:
    pattern: "import.*React"

when:
  builtin.filecontent:
    pattern: "import.*React"
    filePattern: "\\.tsx$"

when:
    builtin.file:
      pattern: "*.go"

when:
  or:
   - builtin.hasTags:
     - Golang
     - Kubernetes

when:
  go.referenced:
    pattern: "v1beta1.CustomResourceDefinition"

when:
  - go.dependency:
      name: sigs.k8s.io/structured-merge-diff/v4

when:
  - go.dependency:
      name: sigs.k8s.io/structured-merge-diff/v4
      upperbound: v4.2.2

when:
  - go.dependency:
      name: sigs.k8s.io/structured-merge-diff/v4
      lowerbound: v4.2.0

The builtin is an internal provider that can analyze various files and internal metadata generated by the engine. This provider has the following capabilities:

when:
  builtin.file:
    pattern: "<regular_expression_to_match_filenames>"

when:
  builtin.filecontent:
    filePattern: "<regular_expression_to_match_filenames_to_scope_search>"
    pattern: "<regular_expression_to_match_content_in_the_matching_files>"

when:
  builtin.xml:
    xpath: "<xpath_expressions>"
    filepaths:
      - "/src/file1.xml"
      - "/src/file2.xml"

where:

when:
  builtin.json:
    xpath: "<xpath_expressions>"

where:

when:
  # when more than one tag is given, a logical AND is implied
  hasTags:
    - "tag1"
    - "tag2"

where:

The java provider analyzes Java source code.

This provider has the following capabilities:

when:
  java.referenced:
    pattern: "<pattern>"
    location: "<location>"
    annotated: "<annotated>"

where:

 annotated:
      pattern: org.framework.Bean
      elements:
      - name: url
        value: "http://www.example.com"

See Java condition and capabilities for a detailed explanation on java.referenced capabilities.

when:
  java.dependency:
    name: junit.junit
    upperbound: 4.12.2
    lowerbound: 4.4.0

You can use the dependency capability to check if a Java application has Fabric8 Kubernetes client of version 5.0.100 or lower:

- java.dependency:
    name: io.fabric8.kubernetes-client
    lowerbound: 5.0.100

The go provider analyzes Go source code. This provider’s capabilities are referenced and dependency.

when:
  go.referenced: "<regex_to_find_reference>"

when:
  go.dependency:
    name: "<dependency_name>"
    upperbound: "<version_string>"
    lowerbound: "<version_string>"

where:

The dotnet provider is an external provider used to analyze .NET and C# source code. Currently, the provider supports the referenced capability.

when:
  dotnet.referenced:
    pattern: "<pattern>"
    namespace: "<namespace>"

where:

The java provider allows scoping the search down to certain source code locations.

java.referenced:
  pattern: org.apache.lucene.search*
  location: IMPORT

would match on each of these imports:

import org.apache.lucene.search.Query;
import org.apache.lucene.search.Sort;
import org.apache.lucene.search.SortField;

java.referenced:
  pattern: org.apache.lucene.search*
  location: PACKAGE

would match on each of the following import and the FQN usage:

import org.apache.lucene.search.Query;
import org.apache.lucene.search.Sort;
import org.apache.lucene.search.SortField;

public class Test {
  private org.apache.lucene.search.Query query;
}

For instance, looking for a method named method declared on org.konveyor.MyClass that returns a List of a type that extends java.lang.String and accepts a single parameter:

java.referenced:
  location: METHOD
  pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'

More information about the possibilities of these patterns can be found in the official Java documentaion, which contain all the information for building these patterns in the createPattern(String, int, int, int) section.

 when:
  java.referenced:
   location: TYPE
   pattern: java.util.List

when:
  java.referenced:
    location: ANNOTATION
    pattern: org.framework.Bean
    annotated:
      elements:
        - name: url
          value: "http://www.example.com"

 when:
  java.referenced:
   location: IMPLEMENTS_TYPE
   pattern: java.util.ArrayList

when:
  java.referenced:
    location: RETURN_TYPE
      pattern: javax.persistence.EntityManager
      annotated:
        pattern: javax.enterprise.inject.Produces

when:
  - java.referenced:
      location: VARIABLE_DECLARATION
      pattern: javax.jms.QueueConnectionFactory

when:
  - java.referenced:
      location: FIELD_DECLARATION
      pattern: javax.jms.QueueConnectionFactory

when:
 java.referenced:
   location: METHOD
   pattern: '* java.lang.String'

when:
  java.referenced:
    location: METHOD_CALL
    pattern: java.sql.DriverManager.getConnection(java.lang.String, java.lang.String, java.lang.String)

when:
 java.referenced:
  pattern: javax.xml*

when:
  java.referenced:
    location: CONSTRUCTOR_CALL
    pattern: java.io.FileOutputStream(java.lang.String, boolean)

when:
 java.referenced:
   pattern: org.apache.lucene.search*
   location: IMPORT

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

 when:
  java.referenced:
    pattern: 'org.jboss.system.ServiceMBeanSupport'
    location: INHERITANCE

You can add a query to match against specific annotations and their elements, for example:

when:
  java.referenced:
    location: METHOD
    pattern: org.package.MyApplication.runApplication(java.lang.String)
    annotated:
      pattern: org.framework.Bean
      elements:
      - name: url
        value: "http://www.example.com"

This would match against the runApplication method in the following Java code:

package org.package

import org.framework.Bean;

class MyApplication {

    @Bean(url = "http://www.example.com")
    public String runApplication(String str) {
        // ...
    }
}

The structure of the annotated YAML element is:

annotated:
  pattern: a Java regular expression to match the fully qualified name of the annotation (optional)
  elements: an array of elements to match within the annotation (optional)
  - name: the exact name of the element to match against
    value: a Java regular expression to match the value of the element

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:

when:
  java.referenced:
    location: ANNOTATION
    pattern: org.framework.Bean
    annotated:
      elements:
        - name: url
          value: "http://www.example.com"

The Language Server used by the Java provider is Eclipse’s JDTLS. Internally, the JDTLS uses the Eclipse Java Development Toolkit, which includes utilities for searching code in projects.

In the pattern element of a java.referenced condition, you can search through application code by using these utilities. For more details, see Class SearchPattern, which contains all the information for building these patterns for createPattern(String, int, int, int).

The analyzer provides two basic logical conditions, and and or, which you can use to aggregate results of other conditions.

The and condition performs a logical AND operation on the results of an array of conditions.

The and condition matches when all of its child conditions match, for example:

when:
  and:
    - <condition1>
    - <condition2>

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

The or condition performs a logical OR operation on the results of an array of conditions.

The or condition matches when any of its child conditions matches, for example:

when:
  or:
    - <condition1>
    - <condition2>

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

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.

when:
 or:
  - builtin.xml:
      xpath: "//dependencies/dependency"
      filepaths: "{{poms.filepaths}}"
    from: poms
  - builtin.file:
      pattern: pom.xml
    as: poms
    ignore: true

In the above example, the output of the builtin.file condition is saved as poms:

+

[...]
      as: poms
[...]

The variables of builtin.file can then be used in the builtin.xml condition, by writing from and then using mustache templates in the provider_ condition block.

This is how this particular condition knows how to use the variable set to the name poms.

+

[...]
    from: poms
[...]

Then you can use the variables by setting them as mustached templates in any of the inputs to the provider condition.

+

[...]
      filepaths: "{{poms.filepaths}}"
[...]

[...]
    ignore: true
[...]

In the java provider, the filepaths variable must be uppercased. for example:

  when:
    and:
      - java.referenced:
          pattern: org.springframework.web.bind.annotation.RequestMapping
          location: ANNOTATION
        as: annotation
      - java.referenced:
          pattern: org.springframework.stereotype.Controller
          location: ANNOTATION
          filepaths: "{{annotation.Filepaths}}"

Conditions can also be nested within other conditions.

when:
  and:
  - and:
    - go.referenced: "*CustomResourceDefinition*"
    - java.referenced:
        pattern: "*CustomResourceDefinition*"
  - go.referenced: "*CustomResourceDefinition*"

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 template messages in a rule’s action (see Message actions). They can be added to a rule in the customVariables field:

- ruleID: lang-ref-004
   customVariables:
   - pattern: '([A-z]+)\.get\(\)'
      name: VariableName
    message: "Found generic call - {{ VariableName }}"
  when:
      java.referenced:
          location: METHOD_CALL
          pattern: com.example.apps.GenericClass.get

where:

A tag action instructs the analyzer to generate one or more tags for the application when a match is found. Each string in the tag field can be a comma-separated list of tags. Optionally, you can assign categories to tags.

tag:
  - "tag1,tag2,tag3"
  - "Category=tag4,tag5"

Example

- ruleID: test-rule
  when:
    <CONDITION>
  tag:
  - Language=Golang
  - Env=production
  - Source Code

A tag can be a string or a key=val pair, where the key is treated as a tag category in MTA. Any rule that has a tag action is referred to as a “tagging rule” in this document.

A message action is used to generate an issue with the specified message when a rule condition matches the source code, for example:

- ruleID: test-rule
  message: Test rule matched. Please resolve this migration issue.
  when:
    <CONDITION>

Optionally, a message can include hyperlinks to external URLs that provide relevant information about the issue or a quick fix.

links:
  - url: "konveyor.io"
    title: "Short title for the link"

You can also create a template message to include information about the match that has been interpolated through custom variables on the rule.

- ruleID: lang-ref-004
   customVariables:
   - pattern: '([A-z]+)\.get\(\)'
      name: VariableName
    message: "Found generic call - {{ VariableName }}"
  when:
    <CONDITION>

Hyperlinks can be provided along with a message or tag action to provide relevant information about the issue, which has been discovered:

# links point to external hyperlinks
# rule authors are expected to provide
# relevant hyperlinks for quick fixes, docs and so on.
links:
  - url: "konveyor.io"
    title: "short title for the link"

MTA YAML-based rules have the following basic structure:

when(condition)
 message(message)
 tag(tags)

This section guides you through the process of creating and testing your first MTA YAML-based rule. This assumes that you have already installed MTA. See Installing and running the CLI in the CLI Guide for installation instructions.

In this example, you will create a rule to discover instances where an application defines a jboss-web.xml file containing a <class-loading> element and to provide a link to the documentation that describes how to migrate the code.

$ mkdir /home/<USER>/rule.yaml

You can create custom rules for Golang (Go) applications based on the following example.

You can use the following custom rule to check if MTA triggers an incident when it detects the v1beta1.CustomResourceDefinition in the`go` file.

You must create custom rules to analyze `Node.js` applications by using {ProductShortName}. A `Node.js` rule can contain `nodejs.referenced` capability which supports the `pattern` field.

The following example uses a custom rule to check if a .tsx file in the Node.js project imports the React framework.

You must create custom rules to analyze Python applications by using MTA. A Python rule can contain python.referenced capability with the supported fields.

The following example uses two custom rules:

You can create a ruleset by placing one or more custom rules in a directory and creating a ruleset.yaml file at the directory root. When you perform an analysis, you pass this directory as input to the MTA CLI by using the --rules option. All rules in this directory are treated as a part of the ruleset defined by the ruleset.yaml file.

The ruleset.yaml file stores the metadata of the ruleset. You can group multiple similar custom rules and create a ruleset for them. When you pass this directory as input to the MTA CLI using the --rules option, MTA treats all the files in the directory as belonging to the ruleset defined in the ruleset.yaml file.

name: "Name of the ruleset"
description: "Description of the ruleset"
labels:
  - key=val

where:

To perform any application analysis, enter:

$ mta-cli analyze --input=<application_to_analyze> --output=<output_dir> --rules=<custom_rule_dir> --enable-default-rulesets=false