MTA-5290 Rules Development Modularization Work by Pkylas007 · Pull Request #280 · migtools/mta-documentation

Pkylas007 · 2025-12-15T08:53:37Z

JIRA

MTA-5290

Version

8.0.0

Preview

Modularized Rule Development guide

What changed

Changed the user guide title to Configuring and using rules for MTA analysis.
Introducing assemblies for all sections and introductions in assemblies.
Introduced new modules for nested conditions, custom Go rule, custom Python rule, and custom Node.js rule.
Rewrote the introduction in some of the assemblies and provided internal links to target modules.
Provided examples for Java locations and provider capability fields.

ibragins

LGTM

jmle · 2026-01-12T09:03:53Z

+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:
+
+[source,yaml]
+----
+java.referenced:
+  location: METHOD
+  pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'
+----


We need to change this whole paragraph to what I said in the coment

Sorry, reversed the error while modifying the example. Please check again.

The problem here is that this example is not METHOD_CALL or CONSTRUCTOR_CALL, but just METHOD (which looks for method declarations, not calls). I can't remember now what I said in the earlier comment because it has disappeared for some reason. We need here a METHOD_CALL example, I think I have provided you one somewhere else? We can move this example to the METHOD section

Oh ok, understood. I have removed these descriptions of method_call and constructor_call in the introduction. These locations are explained with examples in the following table.

It's an old introduction and I think it can be modified to be more relevant later.

Pkylas007 · 2026-01-13T05:50:10Z

+  pattern: javax.xml.*
+----
+
+[WARNING]


@jmle Could you let me know if this warning here is correct? If not, I can remove it. It says dot must not be placed after the javax.xml package.

Let's remove this for the moment

Sure, thanks!

anarnold97 · 2026-01-13T12:07:47Z

+ `annotated` :: 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.
+ +


formatting?

Corrected it, thanks!

anarnold97 · 2026-01-13T12:09:00Z

+
+  `labels` :: List of string labels for the rule.
+  `effort` :: Number of expected story points to fix this issue.
+  `links` :: One or more hyperlinks pointing to documentation around the migration issues that you find.+


Corrected, thanks!

anarnold97 · 2026-01-13T12:12:46Z

+* Estimate the total migration effort 
+* Prioritize issues that must be resolved based on the effort
+* Evaluate if a resolution is mandatory through rule category before migrating the applications to the target technologies or platforms
+* Define labels for which {ProductShortName} filters rules to trigger a violation.


Suggested change

* Define labels for which {ProductShortName} filters rules to trigger a violation.

* Define labels for which {ProductShortName} filter rules trigger a violation.

Modified the sentence, thanks!

anarnold97 · 2026-01-13T12:14:52Z

+ *ruleID* :: This is a unique ID for the rule. It must be unique within the ruleset.
+ *labels* :: A list of string labels associated with the rule. (See xref:yaml-rule-labels_rule-yaml-metadata[Labels]).
+ *effort* :: Effort is an integer value that indicates the level of effort needed to resolve this issue.
+ *category* :: Category describes severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more details, see xref:yaml-rule-categories_rule-yaml-metadata[Rule categories].


Suggested change

*category* :: Category describes severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more details, see xref:yaml-rule-categories_rule-yaml-metadata[Rule categories].

*category* :: Category describes the severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more details, see xref:yaml-rule-categories_rule-yaml-metadata[Rule categories].

Added the article, thanks!

anarnold97 · 2026-01-13T12:21:55Z

+
+.Using the provider capability in custom rules
+
+In a rule, the when block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.. The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, etc, to evaluate the source code and dependencies. The provider sends the LSP server a request to check the search query against the application being analyzed. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation.


Suggested change

In a rule, the when block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.. The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, etc, to evaluate the source code and dependencies. The provider sends the LSP server a request to check the search query against the application being analyzed. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation.

In a rule, the when block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.. The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, and so on, to evaluate the source code and dependencies. The provider sends the LSP server a request to check the search query against the application being analyzed. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation.

Replaced etc, thanks!

anarnold97 · 2026-01-13T12:24:30Z

+|Location |Description |Rule condition example
+
+|TYPE|Matches against all types including classes, interfaces, enum, and annotation types that appear anywhere.
+a|The following example looks for occurences of `java.util.List`.


Suggested change

a|The following example looks for occurences of `java.util.List`.

a|The following example looks for occurrences of `java.util.List`.

Corrected the spelling, thanks!

anarnold97 · 2026-01-13T12:25:21Z

+  location: PACKAGE
+----
+
+would match on each of the following import and the FQN usage:


Suggested change

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

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

Corrected, thanks!

anarnold97 · 2026-01-13T12:25:53Z

+|===
+|Location |Description |Rule condition example
+
+|TYPE|Matches against all types including classes, interfaces, enum, and annotation types that appear anywhere.


Suggested change

|TYPE|Matches against all types including classes, interfaces, enum, and annotation types that appear anywhere.

|TYPE|Matches against all types, including classes, interfaces, enums, and annotation types that appear anywhere.

Made the change, thanks!

anarnold97 · 2026-01-13T12:27:44Z

+|FIELD|Matches against a type appearing in a field
+declaration. It can be coupled with an annotation match happening on the field. See
+xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection]
+a|The following example searches if `QueueConnectionFactory` appears in a field declaration and is used to obtain connection to JMS queues. Replace the string `QueueConnectionFactory` with `ConnectionFactory`.


Suggested change

a|The following example searches if `QueueConnectionFactory` appears in a field declaration and is used to obtain connection to JMS queues. Replace the string `QueueConnectionFactory` with `ConnectionFactory`.

a|The following example searches if `QueueConnectionFactory` appears in a field declaration and is used to obtain a connection to JMS queues. Replace the string `QueueConnectionFactory` with `ConnectionFactory`.

Added the article, thanks!

anarnold97 · 2026-01-13T12:30:55Z

+|CLASS (declaration)|Matches against a given method declaration. Can
+be coupled with an annotation match. See
+xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection].


Suggested change

|CLASS (declaration)|Matches against a given method declaration. Can

be coupled with an annotation match. See

xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection].

|CLASS (declaration)|Matches against a given method declaration. It can be coupled with an annotation match. See xref:yaml-annotation-inspection_java-conditions-capabilities[Annotation inspection].

Removed extra spaces, thanks!

anarnold97 · 2026-01-13T12:32:24Z

+    pattern: java.io.FileOutputStream(java.lang.String, boolean)
+----
+|IMPORT|Matches against class imports. You can use it with FQNs or an asterisk (*) to allow for wider matches.
+a|The following example matches with the import of `org.apache.lucene.search` package and sub packages in the source code.


Suggested change

a|The following example matches with the import of `org.apache.lucene.search` package and sub packages in the source code.

a|The following example matches with the import of `org.apache.lucene.search` package and subpackages in the source code.

Combined the word, thanks!

anarnold97 · 2026-01-13T12:33:13Z

+    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:


Suggested change

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:

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:

Removed the comma, thanks!

anarnold97 · 2026-01-13T12:34:21Z

+[role="_abstract"]
+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:


Suggested change

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

The `or` condition matches when _any_ of its child conditions match, for example:

Corrected the error, thanks!

anarnold97 · 2026-01-13T12:35:53Z

+= Chaining in the Java provider
+
+[role="_abstract"]
+In the `java` provider, the `filepaths` variable must be uppercased. for example:


Suggested change

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

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

Replaced the period with a comma, thanks!

anarnold97 · 2026-01-13T12:39:03Z

+= Hyperlinks
+
+[role="_abstract"]
+Hyperlinks can be provided along with a `message` or `tag` action to provide relevant information about the issue, which has been discovered:


Suggested change

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

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

Replaced which with that, thanks!

anarnold97 · 2026-01-13T12:39:30Z

+----
+# links point to external hyperlinks
+# rule authors are expected to provide
+# relevant hyperlinks for quick fixes, docs and so on.


Suggested change

# relevant hyperlinks for quick fixes, docs and so on.

# relevant hyperlinks for quick fixes, docs, and so on.

Added the comma, thanks!

anarnold97 · 2026-01-13T12:41:45Z

+  ----
+
+  `labels` :: List of string labels for the rule.
+  `effort` :: Number of expected story points to fix this issue.


Suggested change

`effort` :: Number of expected story points to fix this issue.

`effort` :: Number of expected story points to resolve this issue.

Replaced fix with resolve, thanks!

anarnold97 · 2026-01-13T12:43:03Z

+= Creating a custom Node.js rule
+
+[role="_abstract"]
+You must create custom rules to analyze `Node.js` applications by using {ProductShortName}. A `Node.js` rule can contain the `nodejs.referenced` capability which supports the `pattern` field. 


Suggested change

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

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

Replaced which with that, thanks!

anarnold97

Some small issues, nothing major

Feel free to merge once you have dealt with these issues

Pkylas007 · 2026-01-15T06:26:17Z

Some small issues, nothing major

Feel free to merge once you have dealt with these issues

Thank you for the corrections! I have updated the suggested changes in the document.

Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>

Pkylas007 force-pushed the mta-5290-rules-modularization branch from d1b70a7 to 9d3e214 Compare December 15, 2025 10:52

Pkylas007 requested review from eemcmullan, ibragins and jmle December 16, 2025 05:26

ibragins approved these changes Dec 16, 2025

View reviewed changes

eemcmullan reviewed Jan 6, 2026

View reviewed changes

jmle suggested changes Jan 9, 2026

View reviewed changes

Pkylas007 changed the title ~~MTA-5290 First commit of Rules Development Modularization Work~~ MTA-5290 Rules Development Modularization Work Jan 9, 2026

Pkylas007 requested a review from jmle January 12, 2026 06:53

Pkylas007 force-pushed the mta-5290-rules-modularization branch from 06a9acb to 9613c25 Compare January 12, 2026 06:58

jmle reviewed Jan 12, 2026

View reviewed changes

Comment thread docs/topics/rules-development/yaml-java-locations.adoc Outdated

jmle suggested changes Jan 12, 2026

View reviewed changes

Comment thread docs/topics/rules-development/yaml-java-locations.adoc Outdated

Comment thread docs/topics/rules-development/yaml-java-locations.adoc Outdated

Comment thread docs/topics/rules-development/yaml-provider-conditions.adoc

Pkylas007 commented Jan 13, 2026

View reviewed changes

Pkylas007 requested a review from jmle January 13, 2026 08:04

jmle approved these changes Jan 13, 2026

View reviewed changes

Pkylas007 requested a review from anarnold97 January 13, 2026 11:16

anarnold97 reviewed Jan 13, 2026

View reviewed changes

anarnold97 requested changes Jan 13, 2026

View reviewed changes

eemcmullan approved these changes Jan 13, 2026

View reviewed changes

Pkylas007 force-pushed the mta-5290-rules-modularization branch from 2874bed to b108dcc Compare January 15, 2026 06:19

MTA-5290 First commit of Rules Development Modularization Work

84f500c

Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>

Pkylas007 force-pushed the mta-5290-rules-modularization branch from 5007009 to 84f500c Compare January 15, 2026 06:46

Pkylas007 merged commit cf04b97 into migtools:main Jan 15, 2026
1 check failed

Pkylas007 deleted the mta-5290-rules-modularization branch February 5, 2026 05:20

		`annotated` :: 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.
		+

	* Define labels for which {ProductShortName} filters rules to trigger a violation.
	* Define labels for which {ProductShortName} filter rules trigger a violation.

	category :: Category describes severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more details, see xref:yaml-rule-categories_rule-yaml-metadata[Rule categories].
	category :: Category describes the severity of the issue for migration. Values can be one of `mandatory`, `potential` or `optional`. For more details, see xref:yaml-rule-categories_rule-yaml-metadata[Rule categories].


		.Using the provider capability in custom rules

		In a rule, the when block is where the conditions for matching the rule are specified. Each provider offers a series of capabilities to do matching.. The search query in the rule condition can contain patterns, code locations, specific dependencies to be found, etc, to evaluate the source code and dependencies. The provider sends the LSP server a request to check the search query against the application being analyzed. When the LSP server returns a match for the search in the source code, the analyzer triggers a violation.

	a\|The following example looks for occurences of `java.util.List`.
	a\|The following example looks for occurrences of `java.util.List`.

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

	\|TYPE\|Matches against all types including classes, interfaces, enum, and annotation types that appear anywhere.
	\|TYPE\|Matches against all types, including classes, interfaces, enums, and annotation types that appear anywhere.

	a\|The following example searches if `QueueConnectionFactory` appears in a field declaration and is used to obtain connection to JMS queues. Replace the string `QueueConnectionFactory` with `ConnectionFactory`.
	a\|The following example searches if `QueueConnectionFactory` appears in a field declaration and is used to obtain a connection to JMS queues. Replace the string `QueueConnectionFactory` with `ConnectionFactory`.

	a\|The following example matches with the import of `org.apache.lucene.search` package and sub packages in the source code.
	a\|The following example matches with the import of `org.apache.lucene.search` package and subpackages in the source code.

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

	The `or` condition matches when _any_ of its child conditions matches, for example:
	The `or` condition matches when _any_ of its child conditions match, for example:

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

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

	# relevant hyperlinks for quick fixes, docs and so on.
	# relevant hyperlinks for quick fixes, docs, and so on.

	`effort` :: Number of expected story points to fix this issue.
	`effort` :: Number of expected story points to resolve this issue.

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

Conversation

Pkylas007 commented Dec 15, 2025

JIRA

Version

Preview

What changed

Uh oh!

ibragins left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anarnold97 Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

anarnold97 Jan 13, 2026 •

edited

Loading