MTA-5290 Modularized Rule Development Guide

Signed-off-by: Prabha Kylasamiyer Sundara Rajan <[email protected]>

Author: Prabha Kylasamiyer Sundara Rajan

assemblies/rules-development-guide/assembly_creating-rule.adoc

@@ -0,0 +1,37 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-creating-rule: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="creating-rule"]
+endif::[]
+ifdef::context[]
+[id="creating-rule_{context}"]
+endif::[]
+= Creating custom rules
+
+:context: creating-rule
+
+[role="_abstract"]
+You can refer to example rules that describe how to create a YAML rule. This assumes that you already have MTA installed. See the MTA CLI Guide for installation instructions.
+
+//This section describes how to create a {ProductShortName} YAML rule. This assumes that you already have {ProductShortName} installed. See the {ProductShortName} {ProductDocUserGuideURL}[_{UserCLIBookName}_] for installation instructions.//
+
+include::topics/rules-development/create-basic-yaml-rule-template.adoc[leveloffset=+1]
+
+include::topics/rules-development/create-first-yaml-rule.adoc[leveloffset=+1]
+
+include::topics/rules-development/create-go-custom-rule.adoc[leveloffset=+1]
+
+include::topics/rules-development/create-nodejs-custom-rule.adoc[leveloffset=+1]
+
+include::topics/rules-development/create-python-custom-rule.adoc[leveloffset=+1]
+
+
+ifdef::parent-context-of-creating-rule[:context: {parent-context-of-creating-rule}]
+ifndef::parent-context-of-creating-rule[:!context:]
+
+:!creating-rule:

assemblies/rules-development-guide/assembly_java-conditions-detailed.adoc

@@ -0,0 +1,36 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-java-conditions-capabilities: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="java-conditions-capabilities"]
+endif::[]
+ifdef::context[]
+[id="java-conditions-capabilities_{context}"]
+endif::[]
+= Java condition and capabilities 
+
+:context: java-conditions-capabilities
+
+[role="_abstract"]
+The `java.referenced` capability in the when condition for Java rules can define search queries for the following fields in the source code:
+
+* Locations - such as the classes, methods, packages and so on
+* Annotations
+* Patterns
+
+You can refer to this section for a detailed explanation on the Locations, Annotations, and Patterns.
+
+include::topics/rules-development/yaml-java-locations.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-annotation-inspection.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-condition-patterns.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-rule-java-conditions-capabilities[:context: {parent-context-of-rule-java-conditions-capabilities}]
+ifndef::parent-context-of-rule-java-conditions-capabilities[:!context:]
+
+:!java-conditions-capabilities:

assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc

@@ -0,0 +1,43 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-logical-chaining-custom-variables: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="logical-chaining-custom-variables"]
+endif::[]
+ifdef::context[]
+[id="logical-chaining-custom-variables_{context}"]
+endif::[]
+= Logical conditions, condition chaining, and custom variables
+
+:context: logical-chaining-custom-variables
+
+[role="_abstract"]
+You can create complex conditions in rules by using the following:
+
+* Logical conditions inform the provider how to handle more than one condition in a when block. You can aggregate or filter conditions using logical operations.
+* Condition chaining uses the output of one condition as the input in another condition of the when block. Assign the output to a variable in one condition and reuse it in other conditions in the when block.
+* Nested conditions to create conditions that depend on the evaluation of other conditions.
+* Custom variables to capture specific information from the code that is evaluated by a rule. You can use the custom variable in the message displayed for the code if it contains a violation defined by the rule.
+
+include::topics/rules-development/yaml-logical-conditions.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-and-condition.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-or-condition.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-chaining-condition-variables.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-chaining-java-provider.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-nested-condition.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-custom-variables.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-rule-logical-chaining-custom-variables[:context: {parent-context-of-rule-logical-chaining-custom-variables}]
+ifndef::parent-context-of-rule-logical-chaining-custom-variables[:!context:]
+
+:!logical-chaining-custom-variables:

assemblies/rules-development-guide/assembly_rule-rulesets.adoc

@@ -0,0 +1,29 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-rule-rulesets: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="rule-rulesets"]
+endif::[]
+ifdef::context[]
+[id="rule-rulesets_{context}"]
+endif::[]
+= Rulesets
+
+:context: rule-rulesets
+
+[role="_abstract"]
+A set of rules forms a ruleset. MTA does not require every rule file to belong to a ruleset, but you can use rulesets to group multiple rules that achieve a common goal and to pass the rules to the rules engine.
+
+To use multiple rule files, you need to place them in a directory and to add a ruleset.yaml file. Then the directory is treated as a ruleset, and you can pass it as input to the `--rules` option.
+Note that if you want to use the `--target` or `--source` option in the CLI, the engine will only select rules that match the label for that target. Therefore, make sure that you have added target or source labels on your rules. See xref:reserved-label_rule-yaml-metadata[Reserved labels] for more details.
+
+include::topics/rules-development/yaml-rulesets.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-rule-rulesets[:context: {parent-context-of-rule-rulesets}]
+ifndef::parent-context-of-rule-rulesets[:!context:]
+
+:!rule-rulesets:

assemblies/rules-development-guide/assembly_rule-yaml-actions.adoc

@@ -0,0 +1,36 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-rule-yaml-actions: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="rule-yaml-actions"]
+endif::[]
+ifdef::context[]
+[id="rule-yaml-actions_{context}"]
+endif::[]
+= Rule actions
+
+:context: rule-yaml-actions
+
+[role="_abstract"]
+You can use rule actions to generate information about the source code. The rule action information can be included in a violation or used to categorize the source code.
+
+Rules can include the following types of actions:
+
+* `Message`: use message action to display an informative message in the static report that contains the violation triggered by the rule. See xref:yaml-message-actions_rule-yaml-actions[Message action] for more information.
+* `Tag`: use tags to categorize parts of the source code. For example, Backend=Java, where Backend is the key and Java is the value. See xref:yaml-tag-actions_rule-yaml-actions[Tag actions] for more information.
+Each rule includes either one of them or both of them. 
+
+include::topics/rules-development/yaml-tag-actions.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-message-actions.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-rule-hyperlinks.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-rule-yaml-actions[:context: {parent-context-of-rule-yaml-actions}]
+ifndef::parent-context-of-rule-yaml-actions[:!context:]
+
+:!rule-yaml-actions:

assemblies/rules-development-guide/assembly_rule-yaml-conditions.adoc

@@ -0,0 +1,60 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-rule-provider-conditions: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="rule-provider-conditions"]
+endif::[]
+ifdef::context[]
+[id="rule-provider-conditions_{context}"]
+endif::[]
+= Providers and rule conditions 
+
+:context: rule-provider-conditions
+
+[role="_abstract"]
+The providers are the modular components in charge of analyzing a given language. Providers are able to analyze code by leveraging the Language Server Protocol (LSP). Through the LSP, all code analysis is abstracted away from the analysis engine and left to the specific LSP server to run the search query defined in the rule on the source code. 
+
+Additionally, {ProductShortName} provides a built-in provider with abilities such as XML parsing, running regular expressions on files, and so on.
+
+Currently, {ProductShortName} supports the following providers:
+
+* Builtin
+* Java 
+* Go 
+* External providers (for `Python`, `Dotnet` and `Node.js` applications) initialized by the generic provider binary
+
+[NOTE]
+====
+You can use the generic provider binary to create an external provider for any language that is compliant with link:https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/[LSP 3.17 specifications].
+====
+
+.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.
+
+The syntax for the when block is as follows: contains one condition, but that condition can have multiple conditions nested under it.
+
+----
+when:
+  <condition>
+    <nested-condition>
+----
+
+include::topics/rules-development/yaml-provider-conditions.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-builtin-provider.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-java-provider.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-go-provider.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-dotnet-provider.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-rule-provider-conditions[:context: {parent-context-of-rule-provider-conditions}]
+ifndef::parent-context-of-rule-provider-conditions[:!context:]
+
+:!rule-provider-conditions:

assemblies/rules-development-guide/assembly_rule-yaml-metadata.adoc

@@ -0,0 +1,36 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-rule-yaml-metadata: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="rule-yaml-metadata"]
+endif::[]
+ifdef::context[]
+[id="rule-yaml-metadata_{context}"]
+endif::[]
+= Rule metadata
+
+:context: rule-yaml-metadata
+
+[role="_abstract"]
+The rule metadata contains information about the migration defined by the Architect. You can use rule metadata to:
+
+* 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.
+
+
+include::topics/rules-development/yaml-rule-metadata.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-rule-labels.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-rule-categories.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-rule-yaml-metadata[:context: {parent-context-of-rule-yaml-metadata}]
+ifndef::parent-context-of-rule-yaml-metadata[:!context:]
+
+:!rule-yaml-metadata:

assemblies/rules-development-guide/assembly_rules-introduction.adoc

@@ -0,0 +1,30 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-05-28
+
+ifdef::context[:parent-context-of-rules-introduction: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="rules-introduction"]
+endif::[]
+ifdef::context[]
+[id="rules-introduction_{context}"]
+endif::[]
+= Introduction to rules
+
+:context: rules-introduction
+
+[role="_abstract"]
+This guide is intended for software engineers who want to create custom YAML-based rules for {ProductName} ({ProductShortName}) tools.
+
+See the link:{ProductDocIntroToMTAGuideURL}[_{IntroToMTABookName}_] for an overview and the link:{ProductDocUserGuideURL}[_{UserCLIBookName}_] for details.
+
+include::topics/rules-development/about-rules.adoc[leveloffset=+1]
+
+include::topics/rules-development/yaml-rule-structure-syntax.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-getting-started[:context: {parent-context-of-rules-introduction}]
+ifndef::parent-context-of-getting-started[:!context:]
+
+:!rules-introduction:

assemblies/rules-development-guide/topics

@@ -0,0 +1 @@
+../../docs/topics/

docs/rules-development-guide/assemblies

@@ -0,0 +1 @@
+../../assemblies/