Migration toolkit for applications (MTA) analyzes the application source code to find issues based on user-generated and default rule definitions. You can fix issues in an analysis report before migrating the code to a target platform. You can view the rule syntax information to create a new rule or a ruleset.

A ruleset is a collection of one or more rules. An Architect can create rulesets to organize one or more 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 plugins for MTA (Visual Studio Code or IntelliJ).

Red Hat Developer Lightspeed for MTA uses rules to generate AI-assisted code resolutions. Red Hat Developer Lightspeed for MTA uses the issue description and metadata in rules to form well-defined contexts. These contexts generate AI-assisted suggestions to resolve issues in the code that MTA identified through an analysis.

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

You can write rules in YAML. They consist of:

MTA analyzer rules have the following pattern:

ruleID: <Rule_id>
category: mandatory
effort: <Effort_number>
description:
   <Description title>
   <Description text>
labels:
  - konveyor.io/source=<Source_tech>
  - konveyor.io/target=<Target_tech>
links:
 - url: <Hyperlink>
   title: <Hyperlink_title>
when:
 <condition(s)>
message: "message"
tag:
 - <tag_1>, <tag_2>, <tag_3>
 - key_1="<value_1>, <value_2>"

where:

Rule metadata contains a unique rule ID, labels, effort, and category so that the analyzer can select the rules for an analysis and compute the total effort to resolve the issues detected in the source code.

You can use rule metadata to:

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="

You can omit the value of a label. In that case, MTA treats it as an empty value:

labels:
- "konveyor.io/key"

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

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

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

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

Migration toolkit for applications (MTA) applies rule categories per rule. The Architect assigns one of the following rule categories to indicate the risk associated with not resolving an issue.

The external providers, except C#, use the Language Server Protocol (LSP) server to perform an analysis. The provider forms a search query and sends it to the LSP server to check against the application. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation.

Currently, MTA supports the following providers:

As an Architect, you define conditions and patterns in custom rules that MTA uses to match against the source code and dependencies in an analysis. You can specify the conditions in the when block of the rule. You can use capabilities available in each provider to match rule patterns.

The when block contains a single condition, but that condition might have one or more conditions nested under it.

when:
  <condition>
    <nested-condition>

In the rule condition, the Architect defines the patterns that MTA searches for in the source code to trigger an issue. The condition you can define to search an application written in a programming language depends on the capabilities that providers offer.

A rule condition instructs the analyzer to use a specific provider and one of its capabilities. A condition follows the <provider_name>.<capability> pattern.

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

The analyzer currently supports the following providers:

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>

when:
  csharp.referenced:
    <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.

To create a java provider condition that uses the referenced capability:

when:
  java.referenced:
    <fields>

The following table summarizes available providers, their capabilities and 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

  ----
  when:
    csharp.referenced:
      location: CLASS
      pattern: System.Web.Http.ApiController.*
  ----

  ----
  when:
    csharp.referenced:
      location: ALL
      pattern: "System.Console.Print*"
  ----

  ----
  when:
    csharp.referenced:
      location: METHOD
      pattern: "*.AppDomain.Unload"
  ----

  ----
  when:
    csharp.referenced:
      location: FIELD
      pattern: "DotNetOpenAuth.AspNet.AuthenticationResult.Provider"
  ----

  ----
  when:
    csharp.referenced:
      location: ALL
      pattern: "System.Windows.Forms"
  ----

The builtin is an internal provider that can analyze files and internal metadata generated by the rule engine. The builtin provider can parse XML, run regular expressions on files, and scan for application tags.

The builtin provider offers the following capabilities:

The java provider offers referenced and dependency capabilities to analyze Java source code.

The go provider offers referenced and dependency capabilities to analyze Go source code.

The C# provider can analyze .NET and C# application source code by using the referenced capability. The C# provider uses a gRPC interface to perform a semantic analysis of an application source code in the source-only mode.

The provider parses the source code by using tree-sitter and uses stack graph for the analysis to find references to types, methods, classes, and fields. Based on the custom rule definition, the analyzer identifies violations in the source code that Migrators must resolve before the application migration.

when:
  csharp.referenced:
    pattern: "<pattern>"
    location: CLASS

where:

By using the fields in the referenced capability that Java provider supports, you can enable the provider to scope the search down to certain source code locations.

You can use the java.referenced capability in the when condition of the Java rules to search for the following fields:

*IMPORT*: IMPORT allows for searches on class imports. You can use it either with Fully Qualified Names (FQNs) or an asterisk to allow for wider matches:

[source,yaml]
----
java.referenced:
  pattern: org.apache.lucene.search.*
  location: IMPORT
----

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;
----

* *PACKAGE*: the `PACKAGE` location matches on any usage of a package, be
it in an import or used as part of an FQN in the code:

[source,yaml]
----
java.referenced:
  pattern: org.apache.lucene.search.*
  location: PACKAGE
----

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

[source,java]
----
import org.apache.lucene.search.Query;
import org.apache.lucene.search.Sort;
import org.apache.lucene.search.SortField;
----

[source,java]
----
public class Test {
  private org.apache.lucene.search.Query query;
}
----

 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: 'method(java.lang.String) org.konveyor.ExtendedString'

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 use the annotated field in the rule condition to match against specific Java annotations and their elements in the source code.

The following example matches against a specific annotation and its elements:

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"

In the pattern field of a java.referenced condition, the analyzer can search through application code by using the Java Development Kit (JDK) utilities. You can use a wildcard or a specific string to locate classes and methods to refine what the analyzer searches for in the source code.

For more details on the JDK utilities, see Class SearchPattern documentation, which contains all the information for building these patterns for createPattern(String, int, int, int).

Review the following examples of condition patterns:

You can create complex rules to combine conditions, use the output of one rule as an input to another, and chain conditions.

The and condition performs a logical AND operation on the results of an array of conditions. The condition matches when all of its child conditions match, for example:

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

For an example rule condition, see:

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 condition matches when any of its child conditions match.

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

For example:

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 condition chaining, where the pattern of one condition becomes the template variable for filtering in another condition. Use condition chaining to scope down the search query to look for a pattern in a subset of files.

For example, you can search for one or more pom.xml files and find dependencies in those subset of pom files and not any other file in your project. You can use logical and and or for chaining conditions.

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

In the earlier example, MTA saves the output of the builtin.file condition in poms:

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

You can use the variables of builtin.file in the builtin.xml condition, by writing from and then using Mustache templates in the provider_ condition block.

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

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

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

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

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

When you use the filepaths variable in a Java rule chained condition, the rule writer must capitalize the variable.

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}}"

As an Architect, you can create nested conditions in a rule to make the analyzer evaluate different levels of conditions. You can combine the logical and and or conditions in a nested condition.

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

You can create custom variables in provider conditions. You can use custom variables to capture relevant information from a line in the source code that violates the rule. MTA interpolates the values of these variables with the piece of data in the source code. You can add variables to a rule in the customVariables field.

You can use the custom variable values to generate detailed template messages in a rule’s action (see Message actions).

- 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 it finds a match. 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 MTA treats the key as a tag category. You can consider any rule that has a tag action as a “tagging rule” in this document.

migration toolkit for applications (MTA) uses a message action to generate an issue with the specified message when a rule condition matches the source code.

- 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 by using custom variables in the rule.

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

As a rule author, you can configure external hyperlinks along with a message or tag action. Hyperlinks provide relevant documentation that helps you to resolve the issue that MTA discovered.

# relevant hyperlinks for quick fixes, docs, and so on.
links:
  - url: "konveyor.io"
    title: "short title for the link"

You can create a YAML-based 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.

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 pattern in the go file.

You must create custom rules to analyze Node.js applications by using MTA. A Node.js rule contains the nodejs.referenced capability that 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 contains the python.referenced capability with the supported fields.

The following example uses two custom rules:

You can create custom rules to analyze C# applications by using the MTA CLI, user interface, or IDE extension. The following example shows how to run a CLI analysis for a C# application.

You can use a custom rule to check if MTA triggers an incident when it detects the WebMatrix.WebData.WebSecurity class in a C# example project.

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. All rules in this directory become a part of the ruleset.

You can include multiple rules in a ruleset as follows:

To use a custom ruleset in an analysis: